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Chapter 9. Introduction to Message Processing 


Messages are processed by window and dialog procedures. 


Every window has a window procedure. Windows can also be combined into standard 
windows or dialog boxes. These are special cases of groups of windows that also have their 
own procedures. A window or dialog procedure must be capable of processing any 
message. This can be achieved by delegating some message types to the default window, 
or dialog, procedures by use of the WinDefWindowProc and WinDefDlgProc functions 
respectively. 


Control windows are a special type of child windows. They take the form of objects such as 
buttons, scroll bars, list boxes, and text entry fields. These child windows process mouse 
and keyboard input and notify its owner of significant input events. Procedures for these 
child window controls are inside the Presentation Manager and are often called 
system-provided window procedures. 


All messages have the same form as QMSG. structure, which has the following form: 


oe ee 
i 


SPOIL pth 
-ULONG = reserved; 


Message Types 
There are two types of window procedure message processing: 


¢ Default window and dialog procedure message processing 
¢ Control window message processing. 


These types are described below along with the notation conventions used in the message 
descriptions. The messages are described in the following chapters. 
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Default Window and Dialog Procedure Message Processing 


These window procedures provide default processing for application window procedures: 
e Default window and dialog procedure 


e Language support window and dialog procedures, which are used if the application 
specifies a null window procedure 


¢ Default AVIO window procedure. 
These messages are described in Chapter 10, “Default Window Procedure Message 


Processing” on page 10-1. The system-provided window procedures take no action on 
messages that are not defined in this chapter, and return NULL. 


Control Window Message Processing 


9-2 


Controls are predefined classes of child windows that any application can use for input and 
output. These control classes are predefined: 


WC_BUTTON Consists of buttons and boxes that the operator can select by 
clicking the pointing device or using the keyboard. These 
messages are described in Chapter 11, “Button Control 
Window Processing” on page 11-1. 


WC_CIRCULARSLIDER Consists of a visual component whose specific purpose is to 
allow a user to set, display, or modify a value by moving the 
slider arm around the circular slider dial. Messages are 
described in Chapter 25, “Circular Slider Control Window 
Messages” on page 25-1. 


WC_COMBOBOX Consists of an entry field control and a list box control merged 
into a single control. The list, which is usually limited in size, 
is displayed below the entry field and offset one dialog box 
unit to its right. These messages are described in 
Chapter 17, “Combination-Box Control Window Processing” 
on page 17-1. 


WC_CONTAINER Consists of a visual component whose specific purpose is to 
hold objects such as executable programs, word processing 
files, graphics images, and database records. Messages are 
described in Chapter 22, “Container Control Window 
Processing” on page 22-1. 


WC_ENTRYFIELD Consists of a single line of text that the operator can edit. 
These messages are described in Chapter 12, “Entry Field 
Contro! Window Processing” on page 12-1. 


WC_FRAME Consists of a composite window. These messages are 
described in Chapter 13, “Frame Control Window Processing” 
on page 13-1. 

WC_LISTBOX Presents a list of text items from which the operator can make 


selections. These messages are described in Chapter 14, 
“List Box Control Window Processing” on page 14-1. 
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WC_MENU 


WC_MLE 


WC_NOTEBOOK 


WC_SCROLLBAR 


WC_SLIDER 


WC_SPINBUTTON 


WC_STATIC 


WC_TITLEBAR 


WC_VALUESET 


Presents a list of items, which may be text displayed 
horizontally as action bars or vertically as pull-down menus. 
Menus are usually used to provide a command interface to 
applications. These messages are described in Chapter 15, 
“Menu Control Window Processing” on page 15-1. 


Consists of a rectangular window that displays multiple lines 
of text that the operator can edit. When it has the focus, the 
cursor marks the current insertion or replacement point. 
These messages are described in Chapter 16, “Multi-Line 
Entry Field Control Window Processing” on page 16-1. 


Consists of a visual component whose specific purpose is to 
organize information on individual pages so that a user can 
find and display that information quickly and easily. 
Messages are described in Chapter 23, “Notebook Control 
Window Processing” on page 23-1. 


Consists of window scroll bars that allow the operator to make 
a request to scroll the contents of an associated window. 
These messages are described in Chapter 18, “Scroll Bar 
Control Window Processing” on page 18-1. 


Consists of a visual component whose specific purpose is to 
allow a user to set, display, or modify a value by moving the 
slider arm along the slider shaft. Messages are described in 
Chapter 24, “Slider Control Window Processing” on 

page 24-1. 


Presents a scrollable ring of choices from which the operator 
can select. These messages are described in Chapter 19, 
“Spin Button Control Window Processing” on page 19-1. 


Consists of simple display items that do not respond to 
keyboard or pointing device events. These messages are 
described in Chapter 20, “Static Control Window Processing” 
on page 20-1. 


Displays the window title or caption and allows the operator to 
move its owner. These messages are described in 

Chapter 21, “Title Bar Control Window Processing” on 

page 21-1. 


Consists of a visual component whose specific purpose is to 
allow a user to select one choice from a group of mutually 
exclusive choices. A value set can use graphical images (bit 
maps or icons), as well as colors, text, and numbers, to 
represent the items that a user can select. Messages are 
described in Chapter 26, “Value Set Control Window 
Processing” on page 26-1. 
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Owner-Notification Messages: Controls are useful because they notify their owners 
when significant events take place. A control notifies its owner by sending a WM_CONTROL 
message or by posting a WM_COMMAND or WM_HELP message. 


* WM_CONTROL 
¢ WM_COMMAND 


Param2 contains information that indicates the source of the WM_COMMAND message: 


CMDSRC_PUSHBUTTON Posted by a pushbutton control 
CMDSRC_MENU Posted by a menu control 
CMDSRC_ACCELERATOR Posted by WinTranslateAccel 
CMDSRC_FONTDLG Posted by a font dialog. 
CMDSRC_OTHER Other source. 

¢ WM_HELP 
Param? contains information that indicates the source of the WM_HELP message: 
CMDSRC_PUSHBUTTON Posted by a pushbutton control 
CMDSRC_MENU Posted by a menu control 
CMDSRC_ACCELERATOR Posted by WinTranslateAccel 
CMDSRC_OTHER Other source. 


Notation Conventions 
Each message description contains: 
Name The message name; a 2-byte identity unique to a message. 


Some message identity values are reserved for the use of the operating 
system, some are available for use by an application. See “Reserved 
Messages” on page 10-1. 


For all messages, the first two or three characters of the name indicate the 
type of window that is related to the message; for example: 


LM List box control 
SBM __ Scroll bar control. 


Cause The principal reason that caused the generation of the message. 
Parameters Input and output parameters pertinent to the message. 


There are always two parameters (param? and param2) and one return 
value. Any or all of the parameters can be NULL. 


Remarks An explanation of the relationship between the parameters in the context of 
the message and an indication of the expected processing of the message. 


Default A definition of how the default window procedures (provided by the system) 
process the message. 


Note: A message is not equivalent to a call of the same name. 
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Chapter 10. Default Window Procedure Message 
Processing 


This system-provided window procedure processes the actions that control the operation of 
windows. 


Purpose 
General window messages are used for standard processing. These messages can be 
requested from the system or sent to the system for information, or for actions such as 
create window, validate window, track mouse movement, and select and deselect actions. 


Reserved Messages 
These message ranges are reserved: 


WM_USER All messages below this value are reserved for system use. Private 
messages must have an identifier with a value of WM_USER or higher. 


Note: The operating system uses certain message values higher than 
WM_USER. These message values should not be used by an 
application. A partial listing of these messages is in the following 
figure: . 


From PMSTDDLG.H: 


#define FDM_FILTER WM_USER+40 
#define FDM_VALIDATE | WM_USER+41 
#define FDM_ERROR WM_USER+42 


#define FNTM FACENAMECHANGED WM USER+50 
#define FNTM POINTSIZECHANGED WM_USER+51 


#define FNTM_STYLECHANGED WM_USER+52 
#define FNTM_COLORCHANGED WM_USER+53 
#define FNTM_UPDATEPREVIEW WM_USER+54 
#define FNTM_FILTERLIST WM_USER+55 


You should scan your header files to see if other messages have been 
defined with values higher than WM_USER. 


General Window Styles 


The window is the mechanism by which the application communicates with the operator. 
Each window can have a window style that controls the appearance and behavior of the 
window. There are also class styles that apply to all the windows of a particular class (class 
being FRAME, BUTTON, and so on). 


© Copyright IBM Corp. 1994 | 10-1 


Window Class Styles 
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These window class styles are available: 


CS_SIZEREDRAW 


CS_SYNCPAINT 


CS_MOVENOTIFY 


CS_CLIPCHILDREN 


CS _CLIPSIBLINGS 


CS_PARENTCLIP 


CS_SAVEBITS 


CS PUBLIC 


CS_HITTEST 


CS_FRAME 


Determines whether a window will be redrawn when sized. 
This style is to be used for a window whose contents are 
sensitive to the size of the window. For example, the data 
in some windows can be scaled up or down to fit the size of 
the Client Area. In other windows, the data remains the 
same size whatever the size of the window; it is merely 
clipped if the window is made smaller. The © 
CS_SIZEREDRAW style is to be used in the first instance 
but not in the second. For more information, see 
WM_CALCVALIDRECTS. 


Window is synchronously repainted. This style causes 
WS_SYNCPAINT to be set for all windows of this class. 


This class style should be used by a child window if it wants 
to be notified with a WM_MOVE message when its parent is 
moved. For more detail, see the WM_MOVE message 
description. 


Causes a window of style WS_CLIPCHILDREN to be 
created, regardless of whether this style bit is specified on 
the create window function. 


Causes a window of style WS_CLIPSIBLINGS to be 
created, regardless of whether this style bit is specified on 
the create window function. 


Causes a window of style WS_PARENTCLIP to be created, | 
regardiess of whether this style bit is specified on the create 
window function. 


Causes a window of style WS_SAVEBITS to be created, 
regardless of whether this style bit is specified on the create 
window function. 


Causes a public window class to be registered. It is an 
error if this parameter is specified on any process other than 
the shell process. 


If set, causes a WM_HITTEST message to be sent to the 
window, before sending any pointing device message. 


If not set, no WM_HITTEST message is sent, and it is 
assumed that the window returns HT_NORMAL if the ~ 
window is not disabled, and HT_ERROR if the window is 
disabled. 


Top-level frame windows do not have CS_HITTEST set. 


If set, all windows of this class are expected to behave as 
frame windows. 
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Window Styles 


These window styles are available: 
WS_SYNCPAINT Window is synchronously repainted. 


This style is set for windows that have Class Style 
CS_SYNCPAINT. Applications can then turn this style on 
and off to vary the window processing. 


System-Provided Window Styles: 


WS_ANIMATE This specifies that window animation will be turned on. 
Windows animation is a visual effect that occurs when the 
window is opened or closed; the window seems to zoom 
out when it is opened, and zoom in when it is closed. 


This visual effect also depends on the Animation setting in 
the System-Settings notebook. If Animation is enabled and 
this window style is set, window animation occurs when the 
window is opened or closed. When Animation is disabled in 
the System-Settings notebook, this style has no effect and 
no window animation occurs. 


WS_CLIPCHILDREN This specifies that the area occupied by the children of a 
window is to be excluded when drawing in that window. 
Normally, it is included. 


WS_CLIPSIBLINGS This specifies that the area occupied by the siblings of a 
window is to be excluded when drawing in that window. 
Normally, it is included. 


WS_DISABLED This specifies that the window is disabled. The default is 
enabled. 

WS_MAXIMIZED This specifies that the frame window is to be created 
maximized. 


When a window is moved or sized in the normal way at 
least one border should remain on the screen. When a 
window is maximized and the maximum size is as large as 
the screen all borders should be positioned just outside the 


screen. 

WS_MINIMIZED . This specifies that the frame window is to be created 
minimized. 

WS_PARENTCLIP This controls how a window is clipped when a drawing 


action takes place into the window. 


Generally, a WS_PARENTCLIP window is not to draw 
outside its window rectangle. 


WS_SAVEBITS This specifies that the screen image of the area under a 
window of this style be saved when the window is made 
visible. 
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WS_VISIBLE This specifies that the window is visible. The default.is 
invisible. 


Note: A window can still be visible, in this sense, even if it 
cannot be seen because it is covered by other 
windows. 


Styles for Windows in Dialogs 
WS_GROUP This identifies the dialog items that make up a group. 


This style is to be specified on the first window of any group. 
Subsequent windows of the group must not have this style. 
The windows of the group must be adjacent siblings. This 
can be done by listing the windows consecutively in 
templates (see “Dialog Template” on page 31-24) or by 
inserting each new window in the group behind the previous 
one (WinCreateWindow). 


WS_TABSTOP: This identifies a dialog item as one to which the operator 
can TAB. 
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General Window Messages 


This section describes the window procedure actions upon receiving the following messages. 


PL_ALTERED 


This message is broadcast to all frame windows when the PrfReset function is issued. 


Parameters 
param1 


hiniUser (HINI) ; 
Handle of the new user profile. 


param2 


hiniSystem (HINI) 
Handle of the new system profile. 


Returns 
ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks 
Applications should refresh their defaults from the user or system profile. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_ACTIVATE 


This message occurs when an application causes the activation or deactivation of a window. 


Parameters 
param1 


usactive (USHORT) 
Active indicator. 


TRUE _ The window is being activated 
FALSE The window is being deactivated. 
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param2 


hwnd (HWND) 
Window handle. 


In the case of activation, hwnd identifies the window being activated. In the case of 
deactivation, hwnd identifies the window being deactivated. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

A deactivation message (that is, a WM_ACTIVATE message with usactive set to FALSE) is 
sent first to the window procedure of the main window being deactivated, before an activation 
message (that is, a WM_ACTIVATE message with usactive set to TRUE) is sent to the 
window procedure of the main window being activated. 


Any WM_SETFOCUS messages with usfocus set to FALSE, are sent before the deactivation 
message. Any WM_SETFOCUS messages with usfocus set to TRUE, are sent after the 
activation message. 


If WinSetFocus is called during the processing of a WM_ACTIVATE message, a 
WM_SETFOCUS message with usfocus set to FALSE is not sent, as no window has the 
focus. | 


If a window is activated before any of its children have the focus, this message is sent to the 
frame window or to its FID_CLIENT, if it exists. 


Note: Except in the instance of a WM_ACTIVATE message, with usactive set to TRUE, an 
application processing a WM_ACTIVATE, or a WM_SETFOCUS message should not 
change the focus window or the active window. If it does, the focus and active 
windows must be restored before the window procedure returns from processing the 
message. For this reason, any dialog boxes or windows brought up during the 
processing of a WM_ACTIVATE, or a WM_SETFOCUS message should be system 
modal. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_ACTIVATE (in Frame Controls) 
¢ WM_ACTIVATE (Language Support Dialog) 
¢ WM_ACTIVATE (Language Support Window) 
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WM_APPTERMINATENOTIFY 


This message is posted when an application (started by another application) terminates. 


Parameters 
param1 


happ (HAPP) 
Application handle. 


param2 


flretcode (ULONG) 
Return code from the terminating application. 


Returns 
ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks 
The WM_APPTERMINATENOTIFY message provides the capability for the starting 
application to be notified when the started application terminates. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


WM_ADJUSTWINDOWPOS 


This message is sent by the WinSetWindowPos call to enable the window to adjust its new 
position or size whenever it is about to be moved. 


Parameters 
param1 


pswp (PSWP) 
SWP structure pointer. 


The structure has been filled in by the WinSetWindowPos function with the 
proposed move or size data. The control can adjust this new position by changing 
the contents of the SWP structure. It can change the x or y fields to adjust its new 
position; or the cx or cy fields to adjust its new size, or the hwndinsertBehind field to 
adjust its new Z-order. 
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param2 


flzero (U“LONG) 
Zero. 


Returns 
filResult (ULONG) 
Window-adjustment status indicators. 


These indicators are passed on to the WM_WiINDOWPOSCHANGED message that is 
sent after the window state change has occurred. Bits 0 through 15 of this parameter 
are reserved for system use and bits 16 through 31 are available for application use. 


0 No changes have been made 
AWP_MINIMIZED The frame window has been minimized. 
AWP. MAXIMIZED The frame window has been maximized. 
AWP_RESTORED The frame window has been restored. 
AWP_ACTIVATE The frame window has been activated. 
AWP_DEACTIVATE _ The frame window has been deactivated. 


Remarks 
Frame controls can respond to this message to reposition themselves or resize themselves 
in the window frame. 


Menu controls respond to this message as follows: 


MS_ACTIONBAR not specified: The SWP cx and SWP cy fields are set so that the 
menu window exactly contains all of the items in the menu. The SWP x and SWP y fields 
are not changed. . 


MS_ACTIONBAR specified and MS_TITLEBUTTON not specified: The items in 
the menu are arranged such that all of the items are visible within the width specified by the 
SWP cx field. This formatting may cause the menu items to be arranged in multiple lines. 
The SWP cx field is set to include all of the lines of the menu. The SWP x and SWP y fields 
are not changed. 


' MS_ACTIONBAR specified and MS_TITLEBUTTON specified: The SWP cx value 
is set to the accumulated width of the items in the menu. The height specified in the SWP 
cy field is not changed. In both instances, the SWP cx and SWP cy fields are only altered if 
SWP_SIZE is specified in the ff field. Instead, the width of MS_TITLEBUTTON menus is 

‘determined by the accumulated width of the items in the menu. 


A list box does two things: 


e Changes the height so as to accommodate an exact number of items. 


e Automatically outsets its border. This means, for example, that the x, y, width, and 
height fields in the resource file specify the working area of the listbox. The border is 
drawn outside this area. 
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The entry field control, if ES_MARGIN is specified, outsets its margin. This means that in 
the resource file, the numbers specified as the x-, and y-position of an entry field control are 
taken to be the position where the first character of text is drawn, not where the lower-left 
corner of the surrounding box is drawn. Similarly, the height and width parameters apply to 
the editable area of the control; consequently, they do not include the margin. 


When a dialog is created with WinCreateDig or WinLoadDlig, a WM_ADJUSTWINDOWPOS 
message is sent to each child window after the dialog window is created, with a pointer to a 
SWP structure containing ff equal to SWP_SIZE | SWP_MOVE and the x, y, cy, and ex fields 
initialized to the current size and position of the window. The message enables the control 
to adjust its size or position, usually to compensate for its border, or margin, or both. 


Default Processing 
The default window procedure takes no action on this message, other than to set ffResult to 
0. 


WM_BEGINDRAG 


This message occurs when the operator initiates a drag operation. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if fPointer is not set to TRUE. 


param2 


fPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE Message resulted from keyboard event. 


re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_BEGINDRAG. 
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Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. 


WM_BEGINSELECT 


This message occurs when the operator initiates a swipe selection. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if fPointer is not set to TRUE. 


param2 


fPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE Message resulted from keyboard event. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_BEGINSELECT. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. 
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WM_BUTTONICLICK 


This message occurs when the operator presses and then releases button 1 of the pointing 
device within a specified period of time, and without moving the mouse. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
rc (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 
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WM_BUTTON1IDBLCLK 


This message occurs when the operator presses button 1 of the pointing. device twice within 
a specified time, as detailed below. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks | 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 
A double-click is recognized if all of the following are true: 

e Two clicks are of the same button. 

¢ No intervening pointing device button is pressed. 


e The two clicks occur within the double-click time interval as defined by the 
SV_DBLCLKTIME system value. 
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¢ The two clicks occur within a small spatial distance. This is defined by the rectangle, the 
length of whose sides parallel to the x- and y-axes are respectively, the 
SV_CXDBLCLICK and SV_CYDBLCLICK system values. The first click is assumed to 
be at the center of this rectangle. 


The keyboard control codes specified by “flags” reflects the keyboard state at the time the 
mouse message was initiated. This may or may not reflect the current keyboard state. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 


Related Messages 
¢ WM_BUTTON1DBLCLK (in Frame Controls) 
¢ WM_BUTTON1DBLCLK (in Multiline Entry Fields) 


WM_BUTTON1DOWN 


This message occurs when the operator presses pointer button one. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the hit 
test process, which determined the window to be associated with this message. For 
details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 
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Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks . 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


It is the responsibility of the application to ensure that the appropriate frame window is 
activated and that the focus is to the appropriate window, by using the WinSetFocus function. 
The keyboard control codes specified by “flags” reflects the keyboard state at the time the 
mouse message was initiated. This may or may not reflect the current keyboard state. 


Default Processing 
The default window procedure activates the window using WinSetActiveWindow, and then 
sets rc to FALSE. 


Related Messages 
¢ WM_BUTTON1DOWN (in Frame Controls) 
¢ WM_BUTTON1IDOWN (in Multiline Entry Fields) 


WM_BUTTON1MOTIONEND 


“This message occurs when the operator completes a drag operation which was initiated by 
pressing button one on the pointing device. 


Parameters 
param 


_ ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
hit-tested window, when the drag operation is terminated. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 
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Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 


WM_BUTTON1MOTIONSTART 


This message occurs when the operator initiates a drag operation by moving the mouse 
while pressing button one on the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
hit-tested window, when the drag operation is started. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 


Returns 
rc (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 
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Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE.. 


WM_BUTTON1UP 


This message occurs when the operator releases button 1 of the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. : 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks | : 

This message is posted to the application queue associated with the window that is to 
receive the pointing device button information. The keyboard control codes specified by 
“flags” reflects the keyboard state at the time the mouse message was initiated. This may or 
may not reflect the current keyboard state. 
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Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message other than to set rc to FALSE. 


Related Messages 
¢ WM_BUTTON1UP (in Frame Controls) 
e WM_BUTTON1UP (in Multiline Entry Fields) 


WM_BUTTON2CLICK 


This message occurs when the operator presses and then releases button 2 of the pointing 
device within a specified period of time, and without moving the mouse. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message: the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 
Returns 


re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 


This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 
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Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 


WM_BUTTON2DBLCLK 
This message occurs when the operator presses button 2 of the pointing device twice within 
a specified time, as detailed in “WM _BUTTON1DBLCLK’” on page 10-12. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks - 

This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. The keyboard control codes specified by “flags” 
reflects the keyboard state at the time the mouse message was initiated. This may or may 
not reflect the current keyboard state. 


10-18 PM Programming Reference Vol II 


Default Processing 
The default window procedure processes this message identically to 


WM_BUTTON1DBLCLK. 


Related Messages 
¢ WM_BUTTON2DBLCLK (in Frame Controls) 


WM_BUTTON2DOWN 


This message occurs when the operator presses button 2 on the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 
fsHitTestres provides the hit-test result. It contains the value returned from the hit 
test process, which determined the window to be associated with this message. For 
details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 
In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 


receive the pointing device button information. 
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It is the responsibility of the application to ensure that the appropriate frame window is 
activated and that the focus is to the appropriate window, by using the WinSetFocus function. 
The keyboard control codes specified by “flags” reflects the keyboard state at the time the 
mouse message was initiated. This may or may not reflect the current keyboard state. 


Default Processing 
The default window procedure processes this message identically to “WM_BUTTON1DOWN” 
on page 10-13. 


Related Messages 
e WM_BUTTON2DOWN (in Frame Controls) 


WM_BUTTON2MOTIONEND 


This message occurs when the operator completes a drag operation which was initiated by 
pressing button two on the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
hit-tested window, when the drag operation is terminated. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks | 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 
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Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 


WM_BUTTON2MOTIONSTART 


This message occurs when the operator initiates a drag operation by moving the mouse 
while pressing button two on the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
hit-tested window, when the drag operation is started. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 


Returns , 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks ; 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 
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WM_BUTTON2UP 


This message occurs when the operator releases button 2 of the pointing device. 


Parameters 
param 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WWM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that is to 
receive the pointing device button information. The keyboard control codes specified by 
“flags” reflects the keyboard state at the time the mouse message was initiated. This may or 
may not reflect the current keyboard state. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message other than to set rc to FALSE. 
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Related Messages 
¢ WM_BUTTON2UP (in Frame Controls) 


WM_BUTTONSCLICK 


This message occurs when the operator presses and then releases button 3 of the pointing 
device within a specified period of time, and without moving the mouse. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-ieft corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 
.*>>> Removed per M.Ng S.Kipp 7/22/94 
Returns 
re (BOOL) 


Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


Default Processing | 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 
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WM_BUTTON3DBLCLK 
This message occurs when the operator presses button 3 of the pointing device twice within 
a specified time, as detailed in “WM_BUTTON1DBLCLK’” on page 10-12. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
rc (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks | | 

This message is posted to the application queue associated with the window that is to 
receive the pointer button information. The keyboard control codes specified by “flags” 
reflects the keyboard state at the time the mouse message was initiated. This may or may 
not reflect the current keyboard state. 


Default Processing | 
The default window procedure processes this message identically to 
WM_BUTTON1DBLCLK. 
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WM_BUTTON3DOWN 


This message occurs when the operator presses button 3 on the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the hit 
test process, which determined the window to be associated with this message. For 
details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointing device button information. 


It is the responsibility of the application to ensure that the appropriate frame window is 
activated and that the focus is to the appropriate window, by using the WinSetFocus function. 
The keyboard control codes specified by “flags” reflects the keyboard state at the time the 
mouse message was initiated. This may or may not reflect the current keyboard state. 


Default Processing 
The default window procedure processes this message identically to “WM_BUTTON1DOWN” 


on page 10-13. 
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WM_BUTTON3MOTIONEND 


This message occurs when the operator completes a drag operation which was initiated by 
pressing button three on the pointing device. . 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
hit-tested window, when the drag operation is terminated. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. . 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 
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WM_BUTTONS3MOTIONSTART 


This message occurs when the operator initiates a drag operation by moving the mouse 
while pressing button three on the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
hit-tested window, when the drag operation is started. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 


Returns ‘ 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 
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WM_BUTTON3UP 


This message occurs when the operator releases button 3 of the pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see “WM_HITTEST” on page 10-50. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that is to 
receive the pointing device button information. The keyboard control codes specified by 
“flags” reflects the keyboard state at the time the mouse message was initiated. This may or 
may not reflect the current keyboard state. 


Default Processing | 
The default window procedure processes this message identically to WM_BUTTON1UP. 
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WM_CALCFRAMERECT 


This message occurs when an application uses the WinCalcFrameRect function. 


Parameters 
param1 


pRect (PRECTL) 
Rectangle structure. 


This points to a RECTL structure. 


param2 


usFrame (USHORT) 
Frame indicator. 


TRUE Frame rectangle provided 
FALSE Client area rectangle provided. 


Returns 
re (BOOL) 
Rectangle-calculated indicator. 


TRUE Successful completion 
FALSE — Error occurred or the calculated rectangle is empty. 


Remarks 

This message is sent to the frame control to perform the appropriate calculation. If the low 
word of MP2 is TRUE, the RECTL structure in MP1 contains a frame window and this 
message calculates the RECTL of the client. If the low word of MP2 is FALSE, MP1 
contains a client window and this message calculates the RECTL of the frame. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
e WM_CALCFRAMERECT (in Frame Controls) 
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WM_CALCVALIDRECTS 


This message is sent from WinSetWindowPos and WinSetMultWindowPos to determine 
which areas of a window can be preserved if a window is sized, and which should be 
redisplayed. 


Parameters 
param1 


pOldNew (PRECTL) 
Window-rectangle structures. 


This points to two RECTL structures. The first structure contains the rectangle of 
the window before the move, the second contains the rectangle of the window after 
the move. The coordinates of the rectangles are relative to the parent window. 


param2 


pNew (PSWP) 
New window position. 


This points to a SWP structure that contains information apeut the window after it is 
resized (see the WinSetWindowPos function). 


Returns 
usAlign (USHORT) 
Alignment control. 


This instructs WinSetWindowPos how to align valid window bits. This value is made up 
from CVR_* flags, as follows: 


CVR_ALIGNLEFT Align with the left edge of the window. 
CVR_ALIGNBOTTOM _ Align with the bottom edge of the window. 
CVR_ALIGNTOP Align with the top edge of the window. 

CVR_ALIGNRIGHT Align with the right edge of the window. 

CVR_REDRAW The whole window is invalid. !f CVR_REDRAW, is set, the 


whole window is assumed invalid, otherwise, the remaining 
flags can be ORed together to get different kinds of alignment. 
For example: 


(CVR_ALIGNLEFT | CVR_ALIGNTOP) 
aligns the valid window area with the top-left of the window. 


0 It is assumed the application has changed the rectangles 
pointed to by pOldNew and pNew itself. 
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Remarks 
This message is not sent if this window has the CS_SIZEREDRAW style, indicating 
size-sensitive window content that must be totally redrawn if sized. 


This enables the application to determine if the position of the window has changed as well 
as its size; this can aid alignment processing. 


These rectangles can be modified by the window procedure to cause parts of the window to 
be redrawn and not preserved. _ 


The window manager tries to preserve the screen image by copying the image described by 
the old rectangle into the image described by the new rectangle. In this way, an application 
can control the alignment of the preserved image as well, by changing the origin of the first 
rectangle. 


If no change is made to either rectangle, the entire window area is preserved. If either 
rectangle is empty, the entire window area is completely redrawn by the operation. 


Note: This functionality can be used to optimize window updating when the window is 
resized. For example, if the application returns that the window is to be aligned with 
the top-left corner, and the top border is sized, the screen data of the window moves 
with the top border. 


In all instances, the rectangles are intersected with the area of the screen that is 
actually visible and the valid area of the window. That is, only the window area that 
contains window information is copied. 


For example, consider an application that has two scroll bars, that are children of the 
client window. When the window is resized, the scroll bars must be completely 
redrawn. By returning rectangles that exclude the scroll bars, the area of the scroll 
bars is completely redrawn, thereby preserving only the part of the screen that is 
worth preserving. 


Default Processing 
The default window procedure processing is to align the valid area with the top-left of the 
window by returning: 


(CVR_ALIGNTOP | CVR_ALIGNLEFT) 


In addition, any child windows intersecting the source rectangle pointed to by pO/ldNew of 
this message, are also offset with the aligned window area. 
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WM_CHAR 


This message is sent when an operator presses a key. 


Parameters 
param1 


fsflags (USHORT) 


Keyboard control codes. 


KC_CHAR 
KC_SCANCODE 


KC_VIRTUALKEY 


KC_KEYUP 
KC_PREVDOWN 


KC_DEADKEY 


KC_COMPOSITE 


KC_INVALIDCOMP 


KC_LONEKEY 


KC_SHIFT 


KC_ALT 


Indicates that usch value is valid. 
Indicates that ucscancode is valid. 


Generally, this is set in all WM_CHAR messages generated 
from actual operator input. However, if the message has 
been generated by an application that has issued the 
WinSetHook function to filter keystrokes, or posted to the 
application queue, this may not be set. 


Indicates that usvk is valid. 


Normally usvk should be given precedence when processing 
the message. 


Note: For those using hooks, when this bit is set, 
KC_SCANCODE should usually be set as well. 


The event is a key-up transition; otherwise it is a down 
transition. 


The key has been previously down; otherwise it has been 
previously up. 


The character code is a dead key. The application is 
responsible for displaying the glyph for the dead key without 
advancing the cursor. 


The character code is formed by combining the current key 
with the previous dead key. 


The character code is not a valid combination with the 
preceding dead key. The application is responsible for 
advancing the cursor past the dead-key glyph and then, if the 
current character is not a space, sounding the alarm and 
displaying the new character code. 


Indicates if the key is pressed and released without any other 
keys being pressed or released between the time the key 
goes down and up. 


The SHIFT state is active when key press or release 
occurred. 


The ALT state is active when key press or release occurred. 
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KC_CTRL The CTRL state was active when key press or release 
occurred. 


ucrepeat (UCHAR) 
Repeat count. 


ucscancode (UCHAR) 
Hardware scan code. 


A keyboard-generated value that identifies the keyboard event. This is the raw scan 
code, not the translated scan code. 


param2 


usch (USHORT) 
Character code. 


The character value translation of the keyboard event resulting from the current 
code page that would apply if the CTRL or ALT keys were not depressed. 


usvk (USHORT) 
Virtual key codes. 


A virtual key value translation of the keyboard event resulting from the virtual key 
code table. The low-order byte contains the vk value, and the high-order byte is 
always set to zero by the standard translate table. 


0 This value applies if fsflags does not contain KC_VIRTUALKEY. 
Returns 


rc (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks ; 
This message is posted to the queue associated with the window that has the focus. 


The set of keys that causes a WM_CHAR message is device-dependent. 


When this message is processed, precedence should normally be given to a valid virtual key 
if there is one contained in the message. 


There are several instances when a window procedure may receive this message with the 
KC_KEYUP bit set, although it did not receive this message for the down transition of the 
key. 

For example, 


e The down transition of the key is translated by the function WinTranslateAccel, into a 
WM_COMMAND, WM_SYSCOMMAND, WM_HELP, or a WM_NULL message. 
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¢ The key down causes the input focus to change (tab to another window, dismiss a 
dialog, exit a program, and so on). 


e Some other event happens that changes the focus between the time that the key is 
pressed down and the time that it is released. 


Applications should normally only process WM_CHAR messages that do not have the 
KC_KEYUP bit set. 


Except for the special instance where the LONEKEY flag is set on an accelerator key 
definition, all translations are done on the down stroke of the character. 


When the current character is a double-byte character then param2 contains both bytes of 
the double-byte character. These bytes are in the order CHAR1FROMMP, 
CHAR2FROMMP. When the current character is a single-byte character, CHAR2FROMMP 
contains 0. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message other than to set rc to FALSE. 


Related Messages 

e WM_CHAR (Default Dialogs) 
WM_CHAR (in Entry Fields) 
WM_CHAR (in Frame Controls) 
WM_CHAR (in List Boxes) 
WM_CHAR (in Multiline Entry Fields) 


Examples 

This example uses the CHARMSG macro to process a WM_CHAR message. It first uses 
the macro to determine if a key was released. It then uses the macro to generate a switch 
statement based on the character received. 
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WM_CHORD 


This message occurs when the operator presses both button one and button two on the 
pointing device. 


Parameters 
param2 


fsHitTestres (USHORT) 
Hit-test result. 


fsHitTestres provides the hit-test result. It contains the value returned from the 
hit-test process, which determines the window to be associated with this message. 
For details of the possible values, see WM_HITTEST. 


Returns 
rc (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks | 
This message is posted to the application queue associated with the window that is to 
receive the pointer-button information. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 


WM_CLOSE 


This message is sent to a frame window to indicate that the window is being closed by the 
user. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Chapter 10. Default Window Procedure Message Processing 10-35 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

This message is sent by the frame to itself as a result of receiving a WM_SYSCOMMAND 
message with SC_CLOSE code set. If this message is passed to WinDefDigProc, this 
function calls WinDismissDlg and passes the DID_CANCEL result code to it. 


Default Processing 
The default window procedure posts a WM_ QUIT message to the appropriate queue and 
sets ulReserved to 0. 


Related Messages 
e WM CLOSE (Default Dialogs) 
e WM _ CLOSE (in Frame Controls) 


Examples 

In this example, the fChanges variable is checked. If it is TRUE, the user is asked if he 
wants to exit without saving any changes. If the user responds by choosing the No button, 
zero is returned and the application does not exit. If the user responds by choosing the Yes 
button, a WM_QUIT message is posted and the application terminates. 
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WM_COMMAND 


“This message occurs when a control has a significant event to notify to its owner, or when a 
key stroke has been translated by an accelerator table. 


Parameters 
param1 


uscmd (USHORT) 
Command value. 


It is the responsibility of the application to be able to relate uscmd to an application 
function. 


param2 


ussource (USHORT) 
Source type. 


identifies the type of control: 
CMDSRC_PUSHBUTTON Posted by a push-button control. uscmd is the 
window identity of the push button. 


CMDSRC_MENU Posted by a menu control. uscrnd is the identity of 
the menu item. 


CMDSRC_ACCELERATOR Posted as the result of an accelerator. uscmd is the 
accelerator command value. 


CMDSRC_FONTDLG Font dialog. uscmd is the identity of the font dialog. 
CMDSRC_FILEDLG File dialog. uscmd is the identity of the file dialog. 
CMDSRC_OTHER Other source. uscmd gives further control-specific 


information defined for each control type. 


uspointer (USHORT) 
Pointer-device indicator. 


TRUE The message is posted as a result of a pointer-device operation. 
FALSE The message is posted as a result of a keyboard operation. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 
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Remarks 
This message is posted to the queue of the owner of the control. 


WM_.Command handles popup menu command identifiers for pickup, putdown and cancel 
drag operations. It determines which items to display based on the state of the lazy drag 
and droppability of the lazy drag set. 


Default Processing | 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
e WM_COMMAND (Default Dialogs) 
e WM_COMMAND (in Button Controls) 
¢ WM_COMMAND (in Menu Controls) 
¢ WM_SYSCOMMAND (in Title Bar Controls) 


WM_CONTEXTMENU 


This message occurs when the operator requests a pop-up menu. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if fPointer is not set to TRUE. 


param2 


usReserved (USHORT) 
Reserved value, 0. 


fPointer (USHORT) 
Input device flag. 


TRUE Message resulted from keyboard event. 
FALSE Message resulted from mouse pointer event. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 
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Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_CONTEXTMENU, or a 
keyboard event, specified by the system value SV_CONTEXTMENUB. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. 


WM_CONTROL 


This message occurs when a control has a significant event to notify to its owner. 


Parameters 
param1 


id (USHORT) 
Control-window identity. 


This is either the id parameter of the WinCreateWindow function or the identity of an 
item in a dialog template. 


usnotifycode (USHORT) 
Notify code. 


The meaning of the notify code depends on the type of the control. For details, 
refer to the section describing that control. 


param2 


ulcontrolspec (ULONG) 
Control-specific information. 


The meaning of the control-specific information depends on the type of the control. 
For details, refer to the section describing that control. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message is sent to the owner of the control, thereby offering it the opportunity to 
perform some activity before returning to the control. 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 

¢ WM_CONTROL (in Button Controls) 
WM_CONTROL (in Entry Fields) 
WM_CONTROL (Language Support Dialog) 
WM_CONTROL (Language Support Window) 
WM_CONTROL (in List Boxes) 
WM_CONTROL (in Multiline Entry Fields) 
WM_CONTROL (in Combination Boxes) 
WM_CONTROL (in Spin Button Controls) 


WM_CONTROLPOINTER 


This message is sent to a owner window of a control when the pointing device pointer moves 
over the control window, allowing the owner to set the pointing device pointer. 


Parameters 
param1 


usidCtl (USHORT) 
Control identifier. 


param2 


hptrNew (HPOINTER) 
Handle of the pointing device pointer that the control is to use. 


Returns 
hptrRet (HPOINTER) 
Returned pointing device-pointer handle that is then used by the control. 


Remarks 
The recommended approach for an application, that does not have specific reasons for 
controlling the pointer appearance, is to pass the message to the default window procedure. 


Default Processing 
The default window procedure returns hptrNew. 
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WM_CREATE 


This message occurs when an application requests the creation of a window. 


Parameters 
param1 


ctidata (PVOID) 
Pointer to control data. 


This points to a Control-Data data structure initialized with the data provided in the 
pCtiData parameter of the WinCreateWindow function. This pointer is also 
contained in the pCREATE parameter. 


This parameter MUST be a pointer rather than a long. 


The first 2 bytes in the data referenced by this pointer should be the total size of the 
data referenced by the pointer, (for example, see the ENTRYFDATA or the 
FRAMECDATA structure). PM requires this information to enable it to ensure that 
the referenced data is accessible to both 16-bit and 32-bit code. 


param2 


pCREATE (PCREATESTRUCT) 
Create structure. 


This points to a CREATESTRUCT data structure. See the description of ct/idata for 
a complete description. 


Returns 
re (BOOL) 
Error indicator. 


TRUE Discontinue window creation 
FALSE Continue window creation. 


Remarks 
This message is sent to the window procedure of the window being created, thus offering it 
an opportunity to initialize that window. 


The window procedure receives this after the window is created but before the window 
becomes visible. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE, which is equivalent to continuing the creation of the window. 
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WM_DESTROY 


This message occurs when an application requests the destruction of a window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

This message is sent to the window procedure of the window being destroyed after it has 
been hidden on the device, thereby offering it an opportunity to perform some termination 
action for that window. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. | 


WM_DRAWITEM 


This notification is sent to the owner of a control each time an item is to be drawn. 


Parameters 
param1 


ididentity (USHORT) 


Window identifier. 


The window identity of the control sending this notification message. 
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param2 


ulcontrolspec (ULONG) 
Control-specific information. 


The meaning of the control-specific information depends on the type of control. For 
details of each control type, refer to the appropriate section. 


Returns 
re (BOOL) 
Item-drawn indicator. 


TRUE The owner has drawn the item, and so the control does not draw it. 
FALSE _ If the item contains text and the owner does not draw the item, the owner 
returns this value and the control draws the item. 


Remarks 

A control can only display some types of information, and emphasize items in a 
control-specific manner. Therefore, if special items are to be displayed or emphasized in a 
special manner, this must be done by the owner window of the control. 


The control window procedure generates this message and sends it to the owner of the 
control, informing the owner that an item is to be drawn, offering the owner the opportunity to 
draw that item and to indicate that either the item has been drawn or that the control is to 
draw it. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


Related Messages 
¢ WM_DRAWITEM (in Frame Controls) 
e WM_DRAWITEM (in List Boxes) 
¢ WM_DRAWITEM (in Menu Controls) 


WM_ENABLE 


This message notifies a windows of a change to its enable state. 


Parameters 
param1 


usnewenabledstate (USHORT) 
New enabled state indicator. 


TRUE The window was set to the enabled state. 
FALSE The window was set to the disabled state, 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns | 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

This message is sent to the window procedure of the window whose enable state has been 
changed, thereby giving it an opportunity to perform some action appropriate to new state of 
the window. 


This is just a notification message. If you want to change the enable state of a window, you 
would use WinEnableWindow 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_ENABLE (in Button Controls) 
¢ WM_ENABLE (in Multiline Entry Fields) 


WM_ENDDRAG 


This message occurs when the operator completes a drag operation. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if fPointer is not set to TRUE. 


\ 
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param2 


fPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE ~— Message resulted from keyboard event. 


Returns 
rc (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_ENDDRAG. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. 


WM_ENDSELECT 


This message occurs when the operator either makes a selection or completes a swipe 
selection. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if fPointer is not set to TRUE. 


param2 


fPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE Message resulted from keyboard event. 
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Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_ENDSELECT. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. ° 


WM_ERROR 


This message occurs when an error is detected in a WinGetMsg or a WinPeekMsg function. 


Parameters 
param1 


userrorcode (USHORT) 
Error code. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The application can detect the error situation after the WinGetMsg or the WinPeekMsg 
function and before the WinDispatchMsg function. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 
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WM_FOCUSCHANGE 


This message occurs when the window possessing the focus is changed. 


Parameters 
param1 


hwndFocus (HWND) 
Focus window handle. 


param2 


usSetFocus (USHORT) 
Focus flag. 


TRUE _ The window is receiving the focus and hwndFocus identifies the window 
losing the focus. 

FALSE The window is losing the focus and hwndFocus identifies the window 
receiving the focus. 


fsFocusChange (USHORT) 
Focus changing indicators. 


The indicators are passed from the WinFocusChange function. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message is sent to both the windows gaining and losing the focus. 


Default Processing 
The default window procedure sends this message to the owner or parent, if it exists and is 
not the desktop. Otherwise, it sets u/Reserved to 0. 


Related Messages 
e WM FOCUSCHANGE (in Frame Controls) 
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WM_FORMATFRAME 


This message is sent to a frame window to calculate the sizes and positions of all of the 
frame controls and the client window. 


Parameters 
param1 


pswp (PSWP) 
Structure array. 


This points to an array that is to hold the SWP structures. 


param2 


pprectl (PRECTL) 
Pointer to client window rectangle. 


This is typically the window rectangle of pswp, but where the window has a wide 
border, as specified by FCF_DLGBORDER for example, the rectangle is inset by 
the size of the border. 


Returns 
ccount (USHORT) 
Count of the number of SWP arrays returned. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set ccount to the default value of 0. 


Related Messages 
e¢ WM_FORMATFRAME (in Frame Controls) 
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WM_HELP 


This message occurs when a control has a significant event to notify to its owner or when a 
key stroke has been translated by an accelerator table into a WM_HELP. 


Parameters 
param1 


uscmd (USHORT) 
Command value. 


It is the responsibility of the application to be able to relate uscmd to an application 
function. 


param2 


~ ussource (USHORT) 
Source type. 


identifies the type of control: 
CMDSRC_PUSHBUTTON Posted by a push-button control. uscmd is the | 
window identity of the push button. 


CMDSRC_MENU Posted by a menu control. uscmd is the identity of 
the menu item. 


CMDSRC_ACCELERATOR Posted as the result of an accelerator. uscmd is the 
accelerator command value. 


CMDSRC_OTHER Other source. uscmd gives further control-specific 
information defined for each control type. 


uspointer (USHORT) 
Pointer-device indicator. 


TRUE If the message is posted as a result of a pointer-device operation 
FALSE _ If the message is posted as a result of a keyboard operation. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message is identical to a WM_COMMAND message, but implies that the application 
should respond to this message by displaying help information. 


This message is posted to the queue of the owner of the control. 
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Default Processing 
The default window procedure sends this message to the parent window, if it exists and is 
not the desktop. Otherwise, it sets u/Reserved to 0. 


Related Messages 
¢ WM_HELP (in Button Controls) 
¢ WM_HELP (in Menu Controls) 


WM_HITTEST 


This message is sent to determine which window is associated with an input from the 
pointing device. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulresult (ULONG) 
Hit-test indicator. 


The application may return one of these values: 


HT_NORMAL The message should be processed as normal. A 
WM_MOUSEMOVE, WM_BUTTON2DOWN, or 
WM_BUTTON1DOWN message is posted to the window. 


HT TRANSPARENT _ The part of the window underneath the pointer is transparent; 
hit-testing should continue on windows underneath this window, 
as if the window did not exist. 


HT DISCARD The message should be discarded; no message is posted to the 
application. 
HT_ERROR As HT_DISCARD, except that if the message is a button-down 


message, an alarm sounds and the window concerned is 
brought to the foreground. 
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Remarks 
This message occurs when an application requests a message by issuing a WinPeekMsg or 
a WinGetMsg function. 


If the message that is to be retrieved represents a pointer related event, this message is sent 
to a window to determine whether the message is in fact destined for that window. 
This message is only sent if the window class has the CS_HITTEST style set. 


Note: The handling of this message determines whether a disabled window can process 
pointing device events. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/result to 
HT_ERROR if the window is disabled, or to HT_NORMAL otherwise. 


WM_HSCROLL 
This message occurs when a horizontal scroll bar control has a significant event to notify to 
its owner. 


Parameters 
param 


usidentifier (USHORT) 
Scroll bar control window identifier. 


param2 


sslider (SHORT) 
Slider position. 


0 Either the operator is not moving the slider with the pointer device, or for 
the instance where uscmd is SB_SLIDERPOSITION the pointer is outside 
the tracking rectangle when the button is released. 


Other Slider position. 
uscmd (USHORT) 


Command. 

SB_LINELEFT Sent if the operator.clicks on the left arrow of the scroll 
bar, or depresses the VK_LEFT key. 

SB_LINERIGHT Sent if the operator clicks on the right arrow of the scroll 
bar, or depresses the VK_RIGHT key. 

SB_PAGELEFT Sent if the operator clicks on the area to the left of the 


slider, or depresses the VK_PAGELEFT key. 
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SB_PAGERIGHT Sent if the operator clicks on the area to the right of the 
slider, or depresses the VK_PAGERIGHT key. 


SB_SLIDERPOSITION _ Sent to indicate the final position of the slider. 


SB_SLIDERTRACK If the operator moves the scroll bar slider with the pointer 
device, this is sent every time the slider position changes. 
SB_ENDSCROLL Sent when the operator has finished scrolling, but only if 
' the operator has not been doing any absolute slider 
positioning. 
Returns 


ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
e WM_HSCROLL (in Horizontal Scroll Bars) 


WM_INITDLG | 


This message occurs when a dialog box is being created. 


Parameters 
param1 


hwnd (HWND) 
Focus window handle. 


The handle of the contro! window that is to receive the input focus. 


param2 


pcreate (PVOID) 
_ Application-defined data area. 


This points to the data area and is passed by the WinLoadDlg, WinCreateDlg, and 
WinDIgBox functions in their pCreateParams parameter. 


This parameter MUST be a pointer rather than a long. 


The first 2 bytes in the data referenced by this pointer should be the total size of the 
data referenced by the pointer, (for example, see the ENTRYFDATA or the 
FRAMECDATA structure). PM requires this information to enable it to ensure that 
the referenced data is accessible to both 16-bit and 32-bit code. 
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Returns 
rc (BOOL) 
Focus set indicator. 


TRUE Focus window is changed. The dialog procedure can change the window to 
receive the focus, by issuing a WinSetFocus whose hwndNewFocus specifies 
the handle of another contro! within the dialog box. 


FALSE Focus window is not changed. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
e WM_INITDLG (Default Dialogs) 


WM_INITMENU 


This message occurs when a menu control is about to become active. 


Parameters 
param1 


smenuid (SHORT) 
Menu-conirol identifier. 


param2 


hwnd (HWND) 
Menu-window handle. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
e¢ WM_INITMENU (in Frame Controls) 
e¢ WM_INITMENU (in Menu Controls) 
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WM_JOURNALNOTIFY 


This message is used to maintain correct operation during journal playback. 


Parameters 
param1 


ulCommand (ULONG) 
Command to journal. 


JRN_QUEUESTATUS — The WinQueryQueueStatus command must be journaled. 
JRN_PHYSKEYSTATE The WinGetPhysKeyState command must be journaled. 


param2 
Data. 


fsQueueStatus (USHORT) 
Queue status. 


See the Summary parameter of the WinQueryQueueStatus function. 


usScanCode (USHORT) 
Scan code. 


See the sc parameter of the WinGetPhysKeyState function. 


param2 contains usScanCode and usKeyState if ul/Command has the value 
JRN_PHYSKEYSTATE. 


usKeyState (USHORT) 
Key State. 


See the /KeyState parameter of the WinGetPhysKeyState function. 


param2 contains usScanCode and usKeyState if uiCommand has the value 
JRN_PHYSKEYSTATE. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

If the WinQueryQueueStatus or the WinGetPhysKeyState functions have new information 
since the last time they were called and there is a journal record hook installed, the journal 
record hook is called with this message to record this new information. 


During playback, this message is interpreted by the system and the appropriate state _ 
restored. 


Data values of the param2 parameter depend on which command is to be journaled. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set u/Reserved to 0. 


WM_MATCHMNEMONIC 


This message is sent by the dialog box to a control window to determine whether a typed 
character matches a mnemonic in its window text. 


Parameters 
param1 


usmatch (USHORT) 
Match character. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Match indicator. 


TRUE Mnemonic found 
FALSE Mnemonic not found, or an error occurred. 


Default Processing 
The default dialog procedure takes no action on this message, other than to set rc to FALSE. 


Related Messages 
¢ WM_MATCHMNEMONIC (in Button Controls) 
¢ WM_MATCHMNEMONIC (Default Dialogs) 
¢ WM_MATCHMNEMONIC (in Static Controls) 


WM_MEASUREITEM 


This notification is sent to the owner of a specific control to establish the height and width for 
an item in that control. 


Parameters 
param1 


sldentity (SHORT) 
Control identifier. 
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param2 


ulControlSpec (ULONG) 
Control-specific information. 


The meaning of the control-specific information depends on the type of control. For 
details of each control type, refer to the appropriate control section. 


Returns 
ReturnCode 


sHeight (SHORT) 
Height of item. 


sWidth (SHORT) 
Width of item. 


Remarks 
When the owner receives this message, it must calculate and return the height and width (for 
a horizontally-scrollable list box control) of an item to the control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set ReturnCode to the default value of 0. 


Related Messages 
¢ WM_MEASUREITEM (in Frame Controls) 
e WM_MEASUREITEM (in List Boxes) 
¢ WM_MEASUREITEM (in Menu Controls) 


WM_MENUEND 


This message occurs when a menu control is about to terminate. 


Parameters 
param1 © 


usmenuid (USHORT) 
Menu-control identifier. 


param2 


hwnd (HWND) 
Menu-control window handle. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
e WM_MENUEND (in Menu Controls) 


WM_MENUSELECT 


This message occurs when a menu item has been selected. 


Parameters 
param1 


usItem (USHORT) 
Identifier of selected item. 


usPostCommand (USHORT) 
Post-command flag. 


TRUE __ Indicates that either a WM_COMMAND, WM_SYSCOMMAND, or 
WM_HELP message is being posted by the menu control on return from 
the owner, subject to rc. 


FALSE Indicates that no message is being posted by the menu control on return 
from the owner, subject to rc. 


param2 


hwnd (HWND) 
Menu-control window handle. 


Returns 
rc (BOOL) 
Post indicator. 


TRUE __ Indicates that either a WM_COMMAND, WM_SYSCOMMAND, or WM_HELP 
message is to be posted by the menu control window procedure. The menu 
is dismissed if the selected item does not have a style of MIA_NODISMISS. 


FALSE _ Indicates that no message is to be posted by the menu control window 
procedure and that the menu is not dismissed. 
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Default Processing | 
The defauit window procedure takes no action on this message, other than to set rc to 
TRUE. 


Related Messages 
e WM_MENUSELECT (in Frame Controls) 
e WM_MENUSELECT (in Menu Controls) 


WM_MINMAXFRAME 


This message is sent to a frame window that is being minimized, maximized, or restored. 


Parameters 
param1 


pswp (PSWP) 
Set window position structure. 


This points to a SWP structure. The structure has the appropriate SWP_* . 
indicators set to describe the operation that is occurring to the window. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE — The message has been processed; the default system actions for the 
operation specified by the pswp parameter to the window are not to be 
performed. 


FALSE The message has been ignored; the default system actions for the operation 
specified by the pswp parameter to the window are to be performed. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_MINMAXFRAME (in Frame Controls) 
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WM_MOUSEMAP 


This message is specific to version 2.1, or higher, of the OS/2 operating system. 


This message is used only by applications that wish to remap mouse messages in the PM 
input queue. It is not recommended for general application usage, and applications should 
NOT process this message in their window procedures. 


Parameters 
param1 


ulPhysButton (ULONG) 
The physical button number (1, 2, or 3). 


param2 


ulMappedButton (ULONG) 
The button to be mapped to (1, 2, or 3). 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

PM will interpret this message when it is read from the PM input queue, as a request to 
remap all subsequent mouse events for the desired button, until another WM_MOUSEMAP 
message is received, cancelling that remap request. This message has no meaning to an 
application. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


WM_MOUSEMOVE 


This message occurs when the pointing device pointer moves. 


Parameters 
param1 


sxMouse (SHORT) 
Pointing device x-coordinate. 


syMouse (SHORT) 
Pointing device y-coordinate. 
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param2 


uswHitTest (USHORT) 
Message result. 


Zero A pointing device capture is currently in progress 
Other The result of the WM_HITTEST message. 


fsflags (USHORT) 
Keyboard control codes. 


In addition to the control codes described with the WM_CHAR message, the 
following keyboard control codes are valid. 


KC_NONE Indicates that no key is pressed 


Returns 
re (BOOL) 
Processed indicator. 


TRUE The window procedure did process the message. 
FALSE The window procedure did not process the message. 


Remarks 
The keyboard control codes specified by “flags” reflects the keyboard state at the time the 
mouse message was initiated. This may or may not reflect the current keyboard state. 


param? contains the position of the pointing device in window coordinates relative to the 
bottom-left corner of the window. 


Default Processing 
The default window procedure sets the pointer shape using the WinSetPointer function and 
sets rc to FALSE. 


Related Messages 
¢ WM_MOUSEMOVE (in Mulitline Entry Fields) 


WM _MOVE 


This message occurs when a window with style CS_MOVENOTIFY changes its absolute 
position. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks : 
The message is sent from WinSetWindowPos, WinSetMultWindowPos, and 
WinScrollWindow. 


The message is sent to any window when it is moved relative to its parent window. In 
addition, a WM_MOVE message is also sent to any children of that window that have style 
CS_MOVENOTIFY. 


The new position of the window is obtained by calling WinQueryWindowRect, and can make 
those rectangle coordinates relative to any window by calling WinMapWindowPoints. 


Note: There are several instances where windows have cause to know if they have been 
moved, and these include the occasions when the window does not change position 
relative to its parent, but does change position relative to the screen (its absolute 
position). 


An example is menus. When a top-level menu control (child of the frame window) 
moves its absolute position as a result of the frame window being moved, the 
top-level menu contro! causes the movement of any pull-down menus along with its 
movement. The same applies to application/dialog box positional grouping. In some 
instances, a dialog box might cause to be moved as the main window is moved, to 
make room for other applications. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 
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WM_MSGBOXDISMISS 


This message notifies the owner of the message when a non-modal message box has been 
dismissed (the message box is no longer visible). 


Parameters 
param 


hwnd (HWND) 
Non-modal window handle. 


param2 


ulButtonid (ULONG) 
Identity of the selected button in the message box. 


Returns 
ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks 
This message is processed within the owner’s window procedure when a non-modal 
message box is dismissed. It is up to the parent to destroy the message box. 


WM_MSGBOXINIT 


This message notifies the owner of the message when a non-modal message box has been 
created and is currently being displayed. 


Parameters 
param1 


hwnd (HWND) 
Non-modal window handle. 


param2 


idWindow (LONG) 
Window identity of the message box. 


Returns 
ulReserved (ULONG) 
Reserved value, must be 0. 
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Remarks 

This message is processed within the owner’s window procedure when a non-modal 
WinMessageBox2 is created. It is up to the owner to store the window handle returned by 
this function. This handle is then used to properly destroy the message box when 
WM_MSGBOXDISMISS is received or when the parent chooses to destroy it. 


WM_NEXTMENU 
This message occurs when either the beginning or the end of the menu is reached by use of 
the cursor control keys. 


Parameters 
param1 


hwndMenu (HWND) 
Menu-control window handle. 


param2 


usPrev (USHORT) 
Previous-menu indicator. 


TRUE Beginning of the menu has been reached 
FALSE End of the menu has been reached. 


Returns 
hwndNewMenu (HWND) 
New menu window handle. 


NULLHANDLE No new menu 
Other New menu window handle. 


Default Processing 
The default window procedure takes no action on this message, other than to set 
hwndNewMenu to NULLHANDLE. 


Related Messages 
e¢ WM_NEXTMENU (in Frame Controls) 
¢ WM_NEXTMENU (in Menu Controls) 
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WM_NULL 


This message is posted to activate message queues or modal loops. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
On receiving this message, the application should simply let the default processing take 
place. 


Default Processing 
The default window procedure takes no action on this message, other than to set ul/Reserved 
to 0. 


10-64 PM Programming Reference Vol I! 


WM_OPEN 


This message occurs when the operator makes an OPEN request. 


Parameters 
param1 


usPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE Message resulted from keyboard event 


param2 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if usPointer is not set to TRUE. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_OPEN. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. 


WM_PACTIVATE 


This message is posted when the Language Support Window or Dialog Procedure processes 
a WM_ACTIVATE message. 


Parameters 
param1 


usactive (USHORT) 
Active indicator. 
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TRUE The window was activated 
FALSE The window was deactivated. 


param2 


hwnd (HWND) 
Window handle. 


in the case of activation, hwnd identifies the window which was activated. in the 
case of deactivation, hwnd identifies the window which was deactivated. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The activation change has already occurred when the application receives this message. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


WM_PAINT 


This message occurs when a window needs repainting. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure issues the WinBeginPaint and WinEndPaint functions, and 
then sets u/Reserved to 0. 
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Related Messages 
e WM_PAINT (in Frame Controls) 
e WM_PAINT (Language Support Dialog) 
¢ WM_PAINT (Langauge Support Window) 


Examples 

This example shows how an application gets a presentation space for drawing by calling the 
WinBeginPaint function. When drawing is complete, the WinEndPaint function is called to 
release the presentation space. 


case WM PAINT: 
hps = WinBeginPaint(hwnd, NULL, &rcl); 


/* drawing routines would go here */ 


WinEndPaint (hps) ; 
return (OL); _ 


WM_PCONTROL | 
This message is posted when the Language Support Window or Dialog Procedure processes 
a WM_CONTROL message. . 


Parameters 
param1 


id (USHORT) 
Control-window identity. 


This is either the id parameter of the WinCreateWindow function or the identity of an. 
item in a dialog template. 


usnotifycode (USHORT) 
Notify code. 


The meaning of the notify code depends on the type of the control. For details, 
refer to the section describing that control. 


param2 


ulZero (ULONG) 
Zero. 


0 ‘The control-specific information in ulcontrolspec of the WM_CONTROL 
message is not available because the information might not be valid when the 
application receives this message.. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The notification from the control has already been processed when the application receives 
this message. 


Default Processing 
The default window procedure takes no action on this message, other than to set ul/Reserved 
to 0. 


WM_PPAINT 
This message is posted when the Language Support Window or Dialog Procedure processes 
a WM_PAINT message. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure issues the WinBeginPaint and WinEndPaint functions, and 
then sets ulReserved to 0. 


Related Messages 
¢ WM_PPAINT (Language Support Dialog) 
e WM_PPAINT (Language Support Window) 
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WM_PRESPARAMCHANGED 


This message is sent when a presentation parameter is set or removed dynamically from a 
window instance using the WinSetPresParam or WinRemovePresParam functions. It is also 
sent to all windows owned by the window whose presentation parameter was changed. 


Parameters 
param1 


idAttrType (ULONG) 
Presentation parameter attribute identity. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message notifies a control when an inherited presentation parameter changes. 


Default Processing © 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_PSETFOCUS 


This message is posted when the Language Support Window or Dialog Procedure processes 
a WM_SETFOCUS message. 


Parameters 
param1 


hwnd (HWND) 
Focus-window handle. 


NULLHANDLE No window lost or received the focus. 
Other Window handle. 
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param2 


usfocus (USHORT) 
Focus flag. 


TRUE The window received the focus. hwnd is the window handle of the 
window which lost the focus, or NULLHANDLE if no window previously 
had the focus. 


FALSE The window lost the focus. hwnd is the window handle of the window 
which received the focus, or NULLHANDLE if no window received the 
focus. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The focus change has already occurred when the application receives this message. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. . 


WM_PSIZE 
This message is posted when the Language Support Window or Dialog Procedure processes 
a WM_SIZE message. 


Parameters 
param1 


scxold (SHORT) 
Old horizontal size. 


scyold (SHORT) 
Old vertical size. 


param2 


scxnew (SHORT) 
New horizontal size. 


scynew (SHORT) 
New vertical size. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The size change has already occurred when the application receives this message. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_PSYSCOLORCHANGE 


This message is posted when the Language Support Window or Dialog Procedure processes 
a WM_SYSCOLORCHANGE message. 


Parameters 
param1 


flOptions (ULONG) 
Options. 


Copied from the flOptions parameter of the WinSetSysColors function. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
All windows in the system are invalidated so that they will be redrawn with the new system 
color. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 
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WM_QUERYACCELTABLE 


This message returns the handle to the accelerator table of a window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
haccel (HACCEL) 
Accelerator table handle. 


NULLHANDLE No accelerator table is associated with the window. 
Other The handle of the accelerator table associated with the window. 


Default Processing 
The default window procedure takes no action on this message, other than to set haccel to 
NULLHANDLE. 


WM_QUERYCONVERTPOS 


This message is sent by an application to determine whether it is appropriate to begin 
conversion of DBCS characters. 


Parameters 
param1 


pCursorPos (PRECTL) 
Cursor position. 


If usCode = QCP_CONVERT, pCursorPos should be updated to contain the position 
of the cursor in the window receiving this message. The position is specified as a 
rectangle in screen coordinates. 


If usCode = QCP_NOCONVERT, pCursorPos should not. be updated. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usCode (USHORT) 


Conversion code. 


QCP_CONVERT Conversion may be performed for the window with the input 
focus, pCursorPos has been updated to contain the position of 
the cursor. 


QCP_NOCONVERT Conversion should not be performed, the window with the input 
focus cannot receive DBCS characters, pCursorPos has not 
been updated. 


Remarks 

This message enables a DBCS application to determine whether the window with the input 
focus can handle DBCS characters. The pCursorPos parameter can be used as a guide for 
positioning any conversion window that the application requires. 


Default Processing 
The default window procedure returns QCP_CONVERT, and updates pCursorPos to the 
following values: 


xleft = -1 
ybottom = -1 
xright = 0 
ytop = 0 


Related Messages 


WM_QUERYCONVERTPOS (in Button Controls) 
WM_QUERYCONVERTPOS (in Title Bar Controls) 
WM_QUERYCONVERTPOS (in Entry Fields) 
WM_QUERYCONVERTPOS (in Frame Controls) 
WM_QUERYCONVERTPOS (in List Boxes) 
WM_QUERYCONVERTPOS (in Menu Controls) 
WM_QUERYCONVERTPOS (in Scroll Bars) 
WM_QUERYCONVERTPOS (in Static Controls) 
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WM_QUERYHELPINFO 


This message returns the help instance associated with a frame window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ihelpinfo (LONG) 
Help information. 


0 No help information associated with the window. 
Other The help information associated with the window. 


Default Processing 
The default window procedure takes no action on this message, other than to set /helpinfo to 
0.. 


WM_QUERYTRACKINFO 


The frame control generates this message on receiving a WM_TRACKFRAME (in Frame 
Controls) message. 


Parameters 
param1 


ustflags (USHORT) 
Tracking flags. 


Contains a combination of one or more TF_* flags as defined in the TRACKINFO 
structure. 


param2 


ptrackinfo (PTRACKINFO) 
Track information structure. 


This points to a TRACKINFO structure. The receiver of this message must modify 
this structure. 
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Returns 
re (BOOL) 
Continue indicator. 


TRUE ~~ Continue sizing or moving 
FALSE Terminate sizing or moving. 


Remarks 
This message is sent to the window procedure of the owner of a frame control or title bar 
control respectively. 


The TRACKINFO data structure specified by the ptrackinfo parameter is not initialized before 
the message is sent. It must be correctly completed before returning. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
e WM_TRACKFRAME (in Title Bar Controls 


WM_QUERYWINDOWPARAMS 


This message occurs when an application queries the window parameters. 


Parameters 
param1 


pwndparams (PWNDPARAMS) 
Window parameter structure. 


This points to a window parameter structure; see “WNDPARAMS’ on page A-207. 


The valid values of fsStatus are WPM_CCHTEXT, WPM_TEXT, 
WPM_CBCTLDATA, and WPM_CTLDATA. 


The flags in fsStatus are cleared as each item is processed. If the call is 
successful, fsStatus is 0. If any item has not been processed, the flag for that item 
is still set. . 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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WM 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks | 
If this message is sent to a window of another process, the information in, or identified by, 
pwndparams must be in memory shared by both processes. 


Default Processing 

The default window procedure sets the cchText, cbPresParams, and cbCtiData parameters 
of the WNDPARAMS data structure identified by the pwndparams to 0, and sets rc to 
FALSE. 


Related Messages 

WM_QUERYWINDOWPARAMS (in Button Controls) 
WM_QUERYWINDOWPARAMS (in Entry Fields) 
WM_QUERYWINDOWPARAMS (in Frame Controls) 
WM_QUERYWINDOWPARAMS (in List Boxes) 
WM_QUERYWINDOWPARAMS (in Menu Controls) 
WM_QUERYWINDOWPARAMS (in Multiline Entry Fields) 
WM_QUERYWINDOWPARAMS (in Scroll Bars) 
WM_QUERYWINDOWPARAMS (in Static Controls) 
WM_QUERYWINDOWPARAMS (in Title Bars) 


QUIT 


“This message is posted to terminate the application. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
It causes WinGetMsg to return rc set to FALSE, rather than to TRUE, as for all other 
messages. 


Note: Applications that call WinPeekMsg rather than WinGetMsg should test explicitly for 
WM_QUIT. 


This message should not be dispatched to the default window procedure. The intent 
of this message is to cause the WinGetMsg loop to terminate. 


Typically this message is posted by the application when the application exit 
command is selected from the action bar. 


This message is also sent to all applications when the system is closing down. To 
reply to this, the application should either cancel the request by issuing an 
WinCancelShutdown function or close itself down by issuing a WinDestroyMsgQueue 
function. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


Examples 

In this example, a WM_CLOSE message is received. If the {Changes flag is set, the 
application calls a function to determine if the user wants to save the changes before exiting. 
This function (called QuerySaveFile in this example) asks the user if he wants to save the 
changes. If the user selects OK, the changes are saved. If the user selects cancel, the 
function returns this value and the application continues normal execution. Otherwise, it 
posts a WM_QUIT message to terminate the application. 


case WM CLOSE: : ’ es 
Tt (echanges). { Le Ghannes ee not been. saved yf 
Et, (QuerySaveFile(hwnd) - = MB CANCEL) { _ Cee 
oe return (are fe do not exit: after an as 


| | piretegoind WM 1 QUIT, @ 
_ return (Oe) o 
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WM_REALIZEPALETTE 


This message is sent to an application whenever changes have been made to the display 
hardware physical color table as a result of another application calling WinRealizePalette. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The application should call WinRealizePalette if it has a palette, or pass it on to the default 
window procedure if it does not. 


If the return value from WinRealizePalette is greater than 0, the application should invalidate 
its window to cause a repaint using the newly-realized palette. 


Default Processing 

The default window procedure calls WinRealizePalette with a NULL hps parameter. This. 
causes the default palette to be realized. If the return value from WinRealizePalette is 
greater than 0, the default window procedure invalidates the window, causing it to be 
repainted with the newly-realized palette. 


WM_SAVEAPPLICATION 


This message is sent by the system to notify an application to save its current state. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
When an application receives this message, it is expected to save its current state by any 
convenient method, for example, in a profile or in an auxiliary file. 


It is the responsibility of the application to use the saved information, as appropriate, when it 
is resumed. 


Even if the application processes this message, it should also pass it to the default window 
procedure, by using the WinDefWindowProc call. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_SEM1 


This message is sent or posted by an application. 


Parameters 
param1 


flAccumBits (ULONG) 
Semaphore value. 


The semaphore values from all the WM_SEM1 messages posted to a queue, are 
accumulated by a logical-OR operation. 


param2 


_ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 
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Remarks . 
If the message is posted, it is merged with any existing WM_SEM1 message on the queue 
by combining the two flAccumBits values using a logical-OR operation. 


The WM_SEM1 messages are queued higher than any other type of message. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. . . 


Examples 

In this example, a thread notifies the client window that it is about to terminate. It sends the 
constant THREADS as the flFlags parameter so that when the client window receives the 
message, it can tell which thread terminated. 


WM_SEM2 


This message is sent or posted by an application. 


Parameters 
param1 


flAccumBits (ULONG) 
Semaphore value. 


The semaphore values from all the WM_SEM2 messages posted to a queue, are 
accumulated by a logical-OR operation. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
If the message is posted, it is merged with any existing WM_SEM2 message on the queue 
by combining the two fiAccumBits values using a logical-OR operation. 


The WM_SEM2 messages are queued above WM_SEM3 and WM_SEM4 messages, and 
above any WM_PAINT or WM_TIMER messages generated by the system, but lower than 
any other message. 


Default Processing 
The default window procedure takes no action on this message, other than to set ul[Reserved 
to 0. 


WM_SEM3 


This message is sent or posted by an application. 


Parameters 
param1 


flAccumBits (ULONG) 
Semaphore value. 


The semaphore values from all the WM_SEM3 messages posted to a queue, are 
accumulated by a logical-OR operation. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
If the message is posted, it is merged with any existing WM_SEM3 message on the queue 
by combining the two fiAccumBits values using a logical-OR operation. 


The WM_SEM3 messages are queued above WM_SEM4 messages, and any WM_TIMER 
messages generated by the system, but lower than any other message. 
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Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


WM_SEM4 


This message is sent or posted by an application. 


Parameters 
parami 


flAccumBits (ULONG) 
Semaphore value. 


The semaphore values from all the WM_SEM4 messages posted to a queue, are 
accumulated by a logical-OR operation. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks : 
If the message is posted, it is merged with any existing WM_SEM4 message on the queue 
by combining the two flAccumBits values using a logical-OR operation. 


The WM_SEM4 messages are queued lower than any other type of message. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 
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WM_SETACCELTABLE 


This message establishes the window accelerator table to be used for translation, when the 
window is active. 


Parameters 
param1 


haccelNew (HACCEL) 
New accelerator table. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE _ Error occurred. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


WM_SETFOCUS 


This message occurs when a window is to receive or lose the input focus. 


Parameters 
param1 


hwnd (HWND) 
Focus-window handle. 


NULLHANDLE _ No window is losing or receiving the focus. 
Other Window handle. 
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param2 


usfocus (USHORT) 
Focus flag. 


TRUE _ The window is receiving the focus. hwnd is the window handle of the 
window losing the focus, or NULLHANDLE if no window previously had 
the focus. 


FALSE The window is losing the focus. hwnd is the window handle of the 
window receiving the focus, or NULLHANDLE if no window is receiving 
the focus. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks . 
This message is sent to the window receiving or losing the focus, thereby giving it the 
opportunity to perform some appropriate processing. 


Note: Except in the instance of WM_ACTIVATE, with usactive set to TRUE, an application 
processing WM_SETFOCUS or WM_ACTIVATE messages should not change the 
focus window or active window. If it does, the focus and active window must be 
restored before the application returns from processing the message. For this 
reason, any dialog boxes or windows brought up during the processing of 
WM_SETFOCUS or WM_ACTIVATE messages should be system modal. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


Related Messages 
¢ WM_SETFOCUS (Language Support Dialog) 
e WM_SETFOCUS (Language Support Window) 


WM_SETHELPINFO 
This message sets the help instance associated with this frame window when the window is 
active. . 


Parameters 
param1 


lhelpinfo (LONG) 
New help information. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE —_ Successful completion 
FALSE — Error occurred. 


Default Processing 
The default window procedure takes no action on this message, other than to set re to 
FALSE. 


WM_SETSELECTION 


This message occurs when a window is selected or deselected. 


Parameters 
param1 


usselection (USHORT) 
Selection flag. 


TRUE The window is selected. 
FALSE _ The window is deselected. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns | 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The window procedure is expected to ee or unhighlight the selected item of the 
window, as appropriate. 


This message is sent to a window when it loses the focus to another window that it does not 


own. It allows an application to remove the selection when the focus is removed to another 
application, but to keep it if, for example, the same application displays a dialog box. 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_SETWINDOWPARAMS 


This message occurs when an application sets or changes the window parameters. 


Parameters 
param1 


pwndparams (PWNDPARAMS) 
Window parameter structure. 


This points to a window parameter structure; see “WWNDPARAMS’ on page A-207. 
The valid values of fsStatus are WPM_TEXT and WPM_CTLDATA. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful operation 
FALSE — Error occurred. 


Remarks 
If this message is sent to a window of another process, the information in, or identified by, 
pwndparams must be in memory shared by both processes. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. ; 


Related Messages 

WM_SETWINDOWPARANMS (in Button Controls) 
WM_SETWINDOWPARAMS (in Entry Fields) 
WM_SETWINDOWPARAMS (in Frame Controls) 
WM_SETWINDOWPARAMS (in List Boxes) 
WM_SETWINDOWPARAMS (in Menu Controls) 
WM_SETWINDOWPARAMS (in Multiline Entry Fields) 
WM_SETWINDOWPARAMS (in Scroll Bars) 
WM_SETWINDOWPARAMS (in Static Controls) 
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¢ WM_SETWINDOWPARAMS (in Title Bar Controls) 


WM_SHOW 


This message occurs when the WS_ VISIBLE state of a window is being changed. 


Parameters 
param1 


usshow (USHORT) 
Show indicator. 


TRUE Show the window 
FALSE Hide the window. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The message is sent after the visibility state has changed. 


In this context, the terms “shown” or “hidden” refer to the state of the WS_VISIBLE style bit. 


This message is not sent when a window is obscured by other windows above it. 


Default Processing 


The default window procedure takes no action on this message, other than to set ulReserved 


to 0. 


WM_SINGLESELECT 


This message occurs when the operator selects a single object. 


Parameters 
param1 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 


window. This value is ignored if usPointer is not set to TRUE. 
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param2 


usPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE Message resulted from keyboard event. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 


This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from a mouse event, specified by the system value SV_SINGLESELECT. 


Default Processing 


The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set rc to FALSE. 


WM_SIZE 


This message occurs when a window changes its size. 


Parameters 
param1 


scexold (SHORT) 
Old horizontal size. 


scyold (SHORT) 
Old vertical size... 


| param2 


scexnew (SHORT) 
~ New horizontal size. 


scynew (SHORT) 
New vertical size. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

This message is not sent by WinCreateWindow when a window is created, and so any 
size-related processing must be done during the WM_CREATE message processing in this 
instance. 


This message is sent after the window has been actually sized, but before any repainting has 
been done. Any resizing or repositioning of child windows that might be necessary a a result 
of the size change is usually done during the processing of this message. 


Note: It is generally unwise to output to the window during the processing of this message, 
because the area drawn might be redrawn, after the WM_SIZE processing is 
complete, by the WinSetWindowPos function. 


The processing of this message for a window which is displaying an advanced VIO 
presentation space must be carried out by the default advanced VIO window 
procedure. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
e WM_SIZE (in Frame Controls) 
e WM_SIZE (Language Support Dialog) 
e WM_SIZE (Language Support Window) 


WM_SUBSTITUTESTRING 


This message is sent from the WinSubstituteStrings call. 


Parameters 
param1 


iindex (USHORT) 
Substitution index. 


A value corresponding to the decimal character in the substitution phrase. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Chapter 10. Default Window Procedure Message Processing 10-89 


Returns 
pString (PSZ) 
String to be substituted. 


This points to a string (character) buffer. 


0 No substitution string 
Other Substitution string. : 


Remarks 

The WinSubstituteStrings call has encountered a substitution phrase in a string. The 
substitution phrase takes the form “%<digit>,” where <digit> is a single decimal character; 
that is, O through 9. 


Default Processing 
The default window procedure takes no action on this message, other than to set pString to 
0. 


WM_SYSCOLORCHANGE 


This message is sent to all main windows when a change is made to the system colors by 
the WinSetSysColors function. 


Parameters 
param1 


flOptions (ULONG) 
Options. 


Copied from the flOptions parameter of the WinSetSysColors function and therefore 
specifies which palette has been changed. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

All windows are invalidated, so that they are redrawn with the new colors. When this 
message is received, applications that depend on the system colors can query the new color 
values with the WinQuerySysColor call. 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_SYSCOLORCHANGE (Language Support Dialog) 
e WM_SYSCOLORCHANGE (Language Support Window) 


WM_SYSCOMMAND 


This message occurs when a control has a significant event to report to its owner or when a 
key stroke has been translated by an accelerator table. 


Parameters 
param1 


uscmd (USHORT) 
Command value. 


The command value can be one of the SC _* values. It is the responsibility of the 
application to be able to relate uscmd to an application function. 


param2 


ussource (USHORT) 
Source type. 


Identifies the type of control: 


CMDSRC_PUSHBUTTON Posted by a push-button control. uscmd is the 
window identifier of the push button. 


CMDSRC_MENU Posted by a menu control. uscmd is the identifier of 
the menu item. 


CMDSRC_ACCELERATOR Posted as the result of an accelerator. uscmd is the 
accelerator command value. 


CMDSRC_OTHER Other source. uscmd gives further control-specific 
information defined for each contro! type. 


uspointer (USHORT) 
Pointing-device indicator. 


TRUE The message is posted as a result of a pointing-device operation. 
FALSE The message is posted as a result of a keyboard operation. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 
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Remarks 
This message is posted to the queue of the owner of the control, thereby offering it the 
opportunity to perform some activity as a result. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_SYSVALUECHANGED 


This message is posted to all main windows when one of the settable system values is 
changed. 


Parameters 
param1 


usChangedFirst (USHORT) 
First system value. 


The first of a contiguous set of system values that has been changed. 


param2 


usChangedLast (USHORT) 
Last system value. 


The last of a contiguous set of system values that has been changed. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


- Remarks 
If usChangedFirst equals usChangedLast, only one system value has changed. 


If an application changes the settable system values, it is the responsibility of the application 
to post this message to all main windows. 


This message is processed by WC_FRAME windows by doing any frame-specific processing 
(such as sending WM_SETBORDERSIZE messages to the size border if 
SV_CX/CYSIZEBORDER system values have changed) and then sending the message to 
the client window if one exists. 


This message is only posted when settable system values change. 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_TEXTEDIT 


This message occurs when the operator requests a direct name edit operation. 


Parameters 
param1 


usPointer (USHORT) 
Input device flag. 


TRUE Message resulted from pointer event 
FALSE Message resulted from keyboard event. 


param2 


ptspointerpos (POINTS) 
Pointer position. 


The pointer position is in window coordinates relative to the bottom-left corner of the 
window. This value is ignored if usPointer is not set to TRUE. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 


Remarks 

This message is posted to the application queue associated with the window that has the 
focus, or with the window that is to receive the pointer-button information. This message will 
result from either a mouse event, specified by the system value SV_TEXTEDIT, ora 
keyboard event, specified by the system value SV_TEXTEDITKB 


Default Processing 
The defauit window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message, other than to set result to FALSE. 
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WM_TIMER 


This message is posted when a timer times out. 


Parameters 
param1 


idTimer (USHORT) 
Timer identity. 


Any timer Ids that are not being used must be passed on the default window 
procedure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


_ Remarks | 
‘This message is always queued and is processed specially by the WinGetMsg and 
WinPeekMsg calls, as follows: 


1. Timers are processed only by the WinGetMsg and WinPeekMsg calls. 
2. A timer posts only one WM_TIMER message at a time. 


3. WM_TIMER messages are queued lower than all other messages except WM_SEM4 
messages. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 
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WM_TRACKFRAME 


This message is sent to a window whenever it is to be moved or sized. 


Parameters 
param1 


fsTrackFlags (USHORT) 
Tracking flags. 


Contains a combination of one or more TF_* flags; for details, see the TRACKINFO 
data structure description. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator 


TRUE _ The operation is successful. 
FALSE _ The operation is unsuccessful, or the operation is terminated. 


Remarks 
Respond to this message by causing a tracking rectangle to be drawn to move or size the 
window. For information, see WinTrackRect. 


Default Processing 
None. 


Related Messages 
¢ WM_TRACKFRAME (in Frame Controls) 


WM_TRANSLATEACCEL 


This message is sent to the focus window whenever a WM_CHAR message occurs. 


Parameters 
param1 


pqamsg (PQMSG) 
Pointer to a QMSG structure. 


Chapter 10. Default Window Procedure Message Processing 10-95 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Translated indicator. 


TRUE The character exists in the accelerator table and has been translated in the 
QMSG¢ structure. 


FALSE The character does not exist in the accelerator table or the window does not 
have an accelerator table. 


Remarks 
Normally, this message is not processed by the focus window, but is passed to its parent, 
which passes it to its parent, until a frame window is reached. 


Default Processing 


The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
* WM_TRANSLATEACCEL (in Frame Controls) 


WM_TRANSLATEMNEMONIC 


This message occurs during frame control processing of a WM_TRANSLATEACCEL 
message. 


Parameters 
param1 


pqmsg (PQMSG) 
Pointer to a 
QMSG structure. QMSG structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE The character has been translated into an accelerator. 
FALSE The character has not been translated into an accelerator. 


Remarks 

This message is sent by the frame control to itself during the processing of a 
WM_TRANSLATEACCEL message, if the frame control does not translate a character into 
an accelerator by use of the frame window or queue accelerator tables. 


When the frame control receives this message, it sends it to the application menu window, 
that is the window with identity FID_ MENU. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
e WM_TRANSLATEMNEMONIC (in Frame Controls) 


WM_UPDATEFRAME 


This message is sent by an application after frame controls have been added or removed 
from the window frame. 


Parameters 
param1 


fiCreateFlags (ULONG) 
Frame-creation flags. 


Contains the FCF_* flags that indicate which frame controls have been added or 
removed. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE Message processed 
FALSE Message ignored. 
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Default Processing | 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
e WM_UPDATEFRAME (in Frame Controls) 


WM_VRNDISABLED 


This message indicates that the window is being sized, or that a WinLockWindowUpdate has 
been issued for the window or one of its parent windows. Direct drawing to the window 
should be suspended. 


Parameters 
param1 


mp1 (VOID) 
Reserved value. 


param2 


mp2 (VOID) 
Reserved value. 


Returns 
returns 


ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The window procedure is expected to suspend direct drawing to the window. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


WM_VRNENABLED 


This message tells a window that its visible region is now unlocked and is valid for drawing 
on. It also contains a message parameter to inform the window if the visible region was 
changed. 
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Parameters 
param1 


ffVisRgnChanged (BOOL) 
Flag indicating whether the visible region has been altered. 


TRUE The visible region has been altered. The application needs to query the 
new visible region. 


FALSE _ The visible region has not been changed. 


param2 


mp2 (VOID) 
Reserved value. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The visible region, in window coordinates, has been sized, moved or unlocked and drawing 
can now resume. The ffVisRgnChanged parameter is TRUE if the visible region was altered, 
telling the application whether it needs to recheck the visible area of the window. Direct 
drawing to the window can be resumed. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_VSCROLL 


This message occurs when a vertical scroll-bar control has a significant event to notify to its 
owner. 


Parameters 
param1 


usidentifier (USHORT) 
Scroll bar-control window identifier. 
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param2 


sslider (SHORT) 
Slider position. 


0 Either the operator is not moving the slider with the pointer device, or for 
the instance when uscmd is SB_SLIDERPOSITION the pointer is outside 
the tracking rectangle when the button is released. 


Other Slider position. 


uscmd (USHORT) 
Command. 


SB_LINEUP 
SB_LINEDOWN 
SB_PAGEUP 
SB_PAGEDOWN 


SB_SLIDERPOSITION 
SB_SLIDERTRACK 


SB_ENDSCROLL 


Returns 
ulReserved (ULONG) 


Reserved value, should be 0. 


Default Processing 


Sent if the operator clicks on the up arrow of the scroll 
bar, or presses the VK_UP key. 


Sent if the operator clicks on the down arrow of the scroll 
bar, or presses the VK_DOWN key. 


Sent if the operator clicks on the area above the slider, or 
presses the VK_PAGEUP key. 


Sent if the operator clicks on the area below the slider, or 
presses the VK_PAGEDOWN key. - 


Sent to indicate the final position of the slider. 


If the operator moves the scroll bar slider with the pointer 
device, this is sent every time the slider position changes. 


Sent when the operator has finished scrolling, but only if 
the operator has not been doing any absolute slider 
positioning. 


The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 


e WM_VSCROLL (in Vertical Scroll Bars) 
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WM_WINDOWPOSCHANGED 
If this message has any of the values of the ff parameter of the SWP structure set, with the 
exception of the SWP_NOADJUST and SWP_NOREDRAW values, it is sent to the window 
procedure of the window whose position is changed. 


This message is also sent if the return value from the WM_ADJUSTWINDOWPOS is not 
NULL. 


Parameters 
param1 


pswp (PSWP) 
SWP structures. 


This points to two SWP structures. The first SWP structure describes the entire 
new window state, whereas the second structure describes the entire old window 
state. The ff parameter of the first structure contains only those indicators 
corresponding to the state changes that occurred. 


param2 


flAwp (ULONG) 
Adjust window position status indicators. 


The AWF_* flags specify the state change of the frame window. 
The return value from the WM_ADJUSTWINDOWPOS message: 


0 The SWP_NOADJUST option has been specified. 
Other Adjust window position status indicators. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. — 


Default Processing 
The default window procedure sets u/Reserved to 0 and sends the following messages, 
based on the values of the ff parameter of the first SWP data structure: 


SWP_SIZE A WM_SIZE with the new window size from the first SWP structure 
SWP_HIDE A WM_SHOW to hide the new window 
SWP_SHOW A WM_SHOW to show the new window. 
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Examples 
This example processes the WM_WINDOWPOSCHANGED message and assigns the two 


structures to pointers. 


10-102 PM Programming Reference Vol II 


Default Dialog Processing 


This section describes how messages are processed by the default dialog procedure. The 
default dialog procedure can be called using WinDefDigProc. A user dialog procedure 
should make this call for all messages that it does not want to process. 


For WM_* messages other than those specified in this section the Default Dialog Procedure 
takes the same action and sets result to the same value as in Chapter 13, “Frame Control 
Window Processing.” In the instance of messages that would be sent to FID_CLIENT, they 
are passed to the default window procedure. 


For any other messages the default window procedure takes no action, other than to set 
reply to NULL. 


WM_CHAR (Default Dialogs) 
For the cause of this message, see “WWM_CHAR’” on page 10-32. 


For a description of the parameters, see “WWM_CHAR’” on page 10-32. 


Default Processing 

If KC_CHAR is the mnemonic for a button that already has the focus, a BM_CLICK is sent to 
that button and rc is set to TRUE. If the button does not have the focus, it receives the 
focus and rc is set to TRUE. 


If usvk contains the value VK_TAB, the focus is set to the next tab item in the dialog. rc is 
set to TRUE. 


If usvk contains the value VK_BACKTAB, the focus is set to the previous tab item in the 
dialog. rc is set to TRUE. 


if usvk contains the value VK_LEFT or VK_UP, the focus is set to the previous item in the 
group. rc is set to TRUE. 


If usvk contains the value VK_RIGHT or VK_BOTTOM, the focus is set to the next item in 
the group. rc is set to TRUE. 


If usvk contains the value VK_ENTER or VK_NEWLINE, and a push button has the focus, a 
BM_CLICK is sent to the button and rc is set to TRUE. If another control in the dialog has 
the focus the dialog is searched for a push button with style BS_DEFAULT. If a push button 
of this style is found, a BM_CLICK is sent to that button and rc is set to TRUE. 


If usvk contains the value VK_ESC, WM_COMMAND is posted, with ussource is set to 
CMDSRC_PUSHBUTTON and uscmd is set to DID_CANCEL. rc is set to TRUE. 


In other instances, if an owner exists the message is sent to the owner, otherwise rc is set to 
FALSE. 
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Related Messages 
¢ WM_CHAR 


WM_CLOSE (Default Dialogs) 
For the cause of this message, see “WM_CLOSE” on page 10-35. 


For a description of the parameters, see “WM CLOSE” on page 10-35. 


Default Processing 
The default dialog procedure responds to this message by dismissing the dialog by issuing 
the WinDismissDlg function with its rc parameter set to DID_ CANCEL. 


Related Messages 
¢ WM_CLOSE 


WM_COMMAND (Default Dialogs) 
For the cause of this message, see WM_COMMAND. 


For a description of the parameters, see WM_COMMAND. 


Default Processing 

The default dialog procedure responds to this message by dismissing the dialog and passing 
uscmd (the control item identifier) as u/Reply of the WinProcessDlg or the WinDIigBox 
function that initiated the dialog. It sets u/Reserved to 0. 


Related Messages 
¢ WM_COMMAND 


WW_INITDLG (Default Dialogs) 
For the cause of this message, see “WM_INITDLG” on page 10-52. 


For a description of the parameters, see “WM_INITDLG’ on page 10-52. 


Remarks 
This message is sent to the dialog procedure, before the dialog box is shown, thereby 
offering the dialog procedure the opportunity to perform the initialization of the dialog box. 


If any string substitutions are made by the WinSubstituteStrings call when the dialog is 
created, the WM_SUBSTITUTESTRING message may have been sent before the 
WM_INITDLG message is sent. 


Default Processing 
The default dialog procedure passes this message to the default window procedure, which 
sets rc to FALSE. 
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Related Messages 
e WM_INITDLG 


WM_MATCHMNEMONIC (Default Dialogs) 
For the cause of this message, see “WM_MATCHMNEMONIC”’ on page 10-55. 


For a description of the parameters, see “WM_MATCHMNEMONIC” on page 10-55. 


Remarks 
This message is only processed by Button and Static Controls; all other controls return 
FALSE. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


_Related Messages 
_ © WM_MATCHMNEMONIC 


WM_QUERYDLGCODE 


This message is sent by the dialog manager to identify the type of control, to determine what 
kinds of messages the control understands, and also to determine whether an input message 
may be processed by the dialog manager or passed down to the control. 


Parameters 
param1 


pQmsg (PQMSG) 
Message queue structure. 


This points to a QMSG structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulDialogCode (ULONG) 
Dialog code information flags. 


DLGC_ENTRYFIELD Identifies an entry field control. Assumed to understand the 
EM_SETSEL message. 
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DLGC_BUTTON Identifies a button item. Assumed to understand the 
BM_CLICK message. 


DLGC_RADIOBUTTON __ Identifies a radio button control. Used with the 
DLGC_BUTTON code. 


DLGC_STATIC Identifies a static control. Static controls are not included in 
arrow key enumeration. 

DLGC_DEFAULT Identifies a default push-button control. 

DLGC_PUSHBUTTON __ Identifies a nondefault push button. 

DLGC_CHECKBOX Identifies a check-box item. Used with the DLGC_BUTTON 
code. 

DLGC_SCROLLBAR Identifies a scroll bar control. 

DLGC_MENU Identifies a menu control. 


DLGC_TABONCLICK Used by static controls to indicate that a mouse click on this 
control will cause focus to be placed on the next control in the 
dialog that has the WP_TABSTOP style. This should be 
useed in combination with the DLGC_STATIC code. 


DLGC_MLE Identifies a multiline entry field control. 


Remarks 

When processing user input, the dialog manager makes some assumptions about the 
operation of specific controls. The dialog manager sends the WM_QUERYDLGCODE 
message to obtain a code that governs what assumptions can be made. 


If the window receiving this message is not a control as defined above, this message returns 
0. 


Default Processing 
The default dialog procedure takes no action on this message, other than to set 
ulDialogCode to NULL. 


Default File Dialog Processing 


This section describes how messages are processed by the default dialog procedure of the 
file dialog. This standard dialog can be used to provide a common, consistent file selection 
function. 


The file dialog’s default procedure can be called using the WinDefFileDigProc function. A 
user-provided subclassing dialog procedure should make this call for all messages that it 
does not process when using the file dialog. 


The default dialog procedure of the file dialog sends the messages listed in this section to 


itself to perform the requested action. This design allows a user-provided dialog procedure 
to customize the file dialog to its own needs. 
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FDM_ERROR 


This message is sent whenever the file dialog is going to display an error message window. 
This allows an application to display its own message, if desired, instead of messages 
provided by the system. 


Parameters 
param1 


usErrorld (USHORT) 
Error message ID. 


This is the ID of the message that is displayed by the file dialog if the default file 
dialog procedure processes the message. 


param2 


A ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usUserReply (USHORT) 
User’s reply. 
0 The file dialog presents the error message for this ID. 
MBID. OK The file dialog processes the reply as if the OK push button was 


pressed in its message window. 


MBID_CANCEL _ The file dialog processes the reply as if the Cancel push button was 
pressed in its message window. 


MBID_RETRY The file dialog processes the reply as if the Retry push button was 
pressed in its message window. 


Remarks 

The application uses this message to provide application-specific error messages in 
response to file dialog errors that are detected during file dialog processing. The application 
can choose whether to allow the dialog to present its message or whether to provide its own 
message and return the response from that message window to the dialog for processing. 


Default Processing 


The WinDefDlgProc function does not expect to receive this message and takes no action on 
it other than to return NULL. 
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FDM_FILTER 


This message is sent before a file that meets the current filter criteria is added to the File list 
box. 


Parameters 
param1 


pFilename (PSZ) 
Pointer to the file name. 


param2 


pEAType (PSZ) 
Pointer to the .TYPE EA extended attribute. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Add the file. 
FALSE Do not add the file. 


Remarks 

The application checks this message to obtain the name and the .TYPE EA extended 
attribute of the file to be added. The application then determines whether or not the file will 
be added. 


When FALSE is returned, the file is not added to the dialog’s list box. 


Default Processing 
The WinDefDlgProc function does not expect to receive this message and takes no action on 
it other than to return FALSE. 


FDM_VALIDATE 


This message is sent when the user selects a file and presses Enter or clicks on the OK 
button, or double-clicks on a file name in the file list box. 


Parameters 
param1 


_ pFileName (PSZ) , 
Pointer to the fully-qualified file name. 
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param2 


usSeltype (USHORT) 
Selection type. 


re (BOOL) 
Validity indicator. 


TRUE File name is valid. 
FALSE _ File name is not valid. 


Remarks 

This message is only sent just before the dialog returns to the caller with the user-selected 
file name. Before this message is sent, pFileName is updated with the user-selected file 
name. The application can determine if this file name is acceptable. For instance, if the file 
dialog is being used to pick a “SaveAs’ file name, the application can check to see if the file 
is read-only. If it is; a warning dialog should be brought up to notify the user. 


When FALSE is returned from a FDM_VALIDATE message, the dialog will not be dismissed 
and the user can continue to use the File Dialog to select an alternate file. 


In multiple file selection dialogs this message is sent for each selected entry within the file list 
box. When the name of the file being validated comes from a selected entry in the list box, 
param2 will contain FDS_LBSELECTION. When the name of the file comes from the file 
name entry field, param2 will contain FDS_EFSELECTION. Single file selection dialogs will 
always return FDS_EFSELECTION in param2 since the returned file name always comes 
from the single line entry field. 


Default Processing 
The WinDefDigProc function does not expect to receive this message and takes no action on | 
it other than to return FALSE. 


Default Font Dialog Processing 


This section describes how messages are processed by the default dialog procedure of the 
font dialog. This standard dialog can be used to provide a common, consistent font selection 
function. 


The font dialog’s default procedure can be called using the WinDefFontDigProc function. A 
user-provided subclassing dialog procedure should make this call for all messages that it 
does not process when using the font dialog. 


The default dialog procedure of the font dialog sends the messages listed in this section to 


itself to perform the requested action. This design allows a user-provided dialog procedure 
to customize the font dialog to its own needs. 
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WM_DRAWITEM (in Font Dialog) 
If the FNTS_OWNERDRAWPREVIEW style is set for a font dialog, this notification message 
is sent to that dialog’s owner whenever the preview window area (sample text) is to be 
drawn. 


Parameters | 
parami 


id (USHORT) 
Window identifier. 


The window ID of the sample area (DID_SAMPLE). 


param2 


pOwnerltem (POWNERITEM) 
Pointer to an OWNERITEM data structure. 


The following list defines the OWNERITEM data structure fields as they apply to the 
font dialog. See “OWNERITEM” on page A-136 for the default field values. 


hwnd (HWND) 

Window handle of the sample area. 
hps (HPS) 

Presentation-space handle. 


fsState (ULONG) 
Reserved. 


fsAttribute (ULONG) 
Reserved. 


fsStateOld (ULONG) 
Reserved. 


fsAttributeOld (ULONG) 
Reserved. 


rciitem (RECTL) 
Item rectangle to be drawn in window coordinates. 


idltem (LONG) 
Reserved. 


hitem (CNRDRAWITEMINFO) 
Reserved. 
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Returns 
re (BOOL) 
Item-drawn indicator. 


TRUE The owner draws the item. 
FALSE _ If the owner does not draw the item, the owner returns this value and the font 
dialog draws the item. 


Remarks 
The font dialog provides this message to give the application the opportunity to provide a 
custom drawn preview area. 


The font dialog default dialog procedure generates this message and sends it to its owner, 
informing the owner that the preview area is to be drawn. The owner is then given the 
opportunity to draw that area and to indicate that the area has been drawn or that the font 
dialog is to draw it. 


Default Processing 
For a description of the default processing, see WM_DRAWITEM. 


FNTM_FACENAMECHANGED 


This message notifies the subclassing application whenever the font family name is changed 
by the user. 


Parameters 
param1 


pFamilyname (PSZ) 
Pointer to the currently-selected face name. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
pFamilyname is the currently selected family name. The application can modify this string if 
it desires. The buffer set aside is the maximum size a face name string can be (FACESIZE). 
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Default Processing 
The WinDefDlgProc function does not expect to receive this message and takes no action on 
it other than to return 0. 


FNTM_FILTERLIST 


This message is sent whenever the Font Dialog is preparing to add a font family name, font 
style type, or point size entry to the combination box fields that contain these parameters. 


Parameters 
param1 


pFontname (PSZ) 
Pointer to the text string that is being added to the combination box. 


param2 


usFieldid (USHORT) 
Field identifier. 


The identifier of the field to which the text string is being added. The identifier can 
be one of the following: 


FNTI_FAMILYNAME _ The text string is an addition to the family name combination 
box. 


FNTI_STYLENAME _ The text string is an addition to the style combination box. 
FNTtPOINTSIZE The text string is an addition to the size combination box. 


usFontType (USHORT) 
Font information. 


The family name, style, or point size that is being added to the combination box. 
Use one of the following to identify the font information that is being added: 


FNTtBITMAPFONT A bit-map font is being added or a point size of a 
bit-map font is being added. 
FNTILVECTORFONT _ Avvector font is being added. 
FNTI_SYNTHESIZED A synthesized font is being added. This value is 
valid for the style field only. 
FNTI_FIXEDWIDTHFONT A fixed width (monospace) font is being added. 
FNTIPROPORTIONALFONT _ A proportionally spaced font is being added. 
FNTI_DEFAULTLIST A point size from the default list (or the 


application-supplied list) is being added. 
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Returns 
re (BOOL) 
Filter indicator. 


TRUE Add the text string to the combination box. 
FALSE Do not add the text string to the combination box. 


Remarks 

The application checks this message to obtain the name and the .TYPE EA extended 
attribute of the file being added. The application then determines whether or not the file will 
be added. 


When FALSE is returned, the file is not added to the dialog’s list box. 


Default Processing 
The WinDefDlgProc function does not expect to receive this message and takes no action on 
it other than to return FALSE. 


FNTM_POINTSIZECHANGED 


This message notifies subclassing applications when the point size of the font is changed by 
the user. 


Parameters 
param1 


pPointSize (PSZ) 
Pointer to the text in the point-size entry field. 


param2 


fxPointSize (FIXED) 
Point size. 


The fxPointSize field in FONTDLG stated in fixed-point notation. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

When the application wants to limit the point sizes the user can select, it should process this 
message by changing the pPointSize value and putting up a message box explaining the 
limitation to the user. 


Chapter 10. Default Window Procedure Message Processing 10-113 


Default Processing 
The WinDefDigProc function does not expect to receive this message and takes no action on 
it other than to return 0. 


FNTM_STYLECHANGED 
This message notifies subclassing applications when the user changes any of the attributes 
in the STYLECHANGE structure. 


Parameters 
param 


stye (STYLECHANGE) 
Style changes. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The “Old” fields show the style attributes before the user made the change. The other 
parameters show what the state will be after the application passes this message to 
WinDefFontDigProc. When the “Old” field and the “New” field are the same, no change is 
made for that attribute. 


Default Processing 
The WinDefDigProc function does not expect to receive this message and takes no action on 
it other than to return 0. 
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FNTM_UPDATEPREVIEW 


This message notifies subclassing applications before the preview window is updated. This 
occurs when the font selection is modified. 


Parameters 
param1 


hwndPreview (HWND) 
Window handle. 


Window handle the preview image is drawn into. This is a static text field. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message notifies an application that the dialog is about to update the preview area. 


Default Processing 
The WinDefDigProc function does not expect to receive this message and takes no action on 
it other than to return 0. 
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Language Support Window Processing 


This system-provided window procedure processes messages for a window that has been 
created with a window class specifying a “NULL” window procedure. 


The following describes the WM_* messages and the language support window procedure 
action. 


For any other messages the Language Support Window Procedure performs the same 
actions as the Default Window Procedure. . 


WM_ACTIVATE (Language Support Window) 
For the cause of this message, see “WM_ACTIVATE” on page 10-5. 


For a description of the parameters, see “WM_ACTIVATE” on page 10-5. 


Remarks 
The Language Support Window Procedure responds to this message by posting a 
WM_PACTIVATE message to the application queue and setting u/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 


, 0 0. 


Related Messages 
¢ WM _ACTIVATE 


WM_CONTROL (Language Support Window) 
For the cause of this message, see WM_CONTROL. 


For a description of the parameters, see WM CONTROL. 


Remarks 
The Language Support Window Procedure responds to this message by posting a 
WM_PCONTROL message to the application queue and setting u/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 


to 0. 


Related Messages 
¢* WM_CONTROL 
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WM_PAINT (Langauge Support Window) 
For the cause of this message, see “WM_PAINT” on page 10-66. 


For a description of the parameters, see “WM_PAINT” on page 10-66. 


Remarks 
The Language Support Window Procedure responds to this message by posting a 
WM_PPAINT message to the application queue and setting ul/Reserved to 0. 


The WinBeginPaint and WinEndPaint functions are issued by the Language Support Window 
Procedure, during the processing of the WM_PPAINT message. 


Default Processing 
The default window procedure issues the WinBeginPaint and WinEndPaint functions, and 


then sets u/Reserved to 0. 


Related Messages 
¢ WM_PAINT 


WM_PPAINT (Language Support Window) 
For the cause of this message, see “WM_PPAINT” on page 10-68. 


For a description of the parameters, see “WM_PPAINT” on page 10-68. 


Remarks 
The Language Support Window Procedure issues the WinBeginPaint and WinEndPaint 
functions, and then sets u/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_PPAINT 
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WM_SETFOCUS (Language Support Window) 
For the cause of this message, see “WM_SETFOCUS’ on page 10-83. 


For a description of the parameters, see “WM_SETFOCUS” on page 10-83. 


Remarks 
The Language Support Window Procedure responds to this message by posting a 
WM_PSETFOCUS message to the application queue and setting u/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set ul/Reserved 


to 0. 


Related Messages 
e WM_SETFOCUS 


WNM_SIZE (Language Support Window) 
For the cause of this message, see WM_SIZE. 


For a description of the parameters, see WM_SIZE. 


Remarks 
The Language Support Window Procedure responds to this message by posting a 
WM_PSIZE message to the application queue and setting ul/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
¢ WM_SIZE 
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WM_SYSCOLORCHANGE (Language Support Window) 
For the cause of this message, see “WM_SYSCOLORCHANGE?” on page 10-90. 


For a description of the parameters, see “WM_SYSCOLORCHANGE?” on page 10-90. 


Remarks 
The Language Support Window Procedure responds to this message by posting a 
WM_PSYSCOLORCHANGE message to the application queue and setting u/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
* WM_SYSCOLORCHANGE 
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Language Support Dialog Processing 


This system-provided window procedure processes messages for a dialog that has been 
created or loaded specifying a ‘NULL’ dialog procedure. . 


For any other messages the Language Support Dialog Procedure issues and returns the 
result of the WinDefDlgProc function. 


WM_ACTIVATE (Language Support Dialog) 
For the cause of this message, see “WM_ACTIVATE” on page 10-5. 


For a description of the parameters, see “WM_ACTIVATE” on page 10-5. 


Remarks 

The Language Support Dialog Procedure responds to this message by issuing the 
WinDefDlgProc function, then posting a WM_PACTIVATE message to the application queue 
and setting u/Reserved to the result of the WinDefDigProc function. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
¢ WM_ACTIVATE 


WM_CONTROL (Language Support Dialog) 
For the cause of this message, see “WM_CONTROL’ on page 10-39. 


For a description of the parameters, see “WM_CONTROL” on page 10-39. 


Remarks 

The Language Support Dialog Procedure responds to this message by issuing the 
WinDefDlgProc function, then posting a WM_PCONTROL message to the application queue 
and setting u/Reserved to the result of the WinDefDlgProc function. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 


to 0. 


Related Messages 
¢ WM_CONTROL 
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WM_PAINT (Language Support Dialog) 
For the cause of this message, see “WM_PAINT” on page 10-66. 


For a description of the parameters, see “WM_PAINT” on page 10-66. 


Remarks 

The Language Support Dialog Procedure responds to this message by issuing the 
WinDefDlgProc function, then posting a WM_PPAINT message to the application queue and 
setting u/Reserved to the result of the WinDefDlgProc function. 


The WinBeginPaint and WinEndPaint functions are issued by the Language Support Dialog 
Procedure, during the processing of the WM_PPAINT message. 


Default Processing 
The default window procedure issues the WinBeginPaint and WinEndPaint functions, and 
then sets ulReserved to 0. 


Related Messages 
¢ WM _PAINT 


WM_PPAINT (Language Support Dialog) 
For the cause of this message, see “WM_PPAINT” on page 10-68. 


For a description of the parameters, see “WM_PPAINT” on page 10-68. 


Remarks 

The Language Support Dialog Procedure issuing the WinDefDlgProc function, then issues 
the WinBeginPaint and WinEndPaint functions, and then setting u/Reserved to the result of 
the WinDefDlgProc function. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
¢ WM_PPAINT 


Chapter 10. Default Window Procedure Message Processing 10-121 


WM_SETFOCUS (Language Support Dialog) 
For the cause of this message, see “WM_SETFOCUS” on page 10-83. 


For a description of the parameters, see “WM_SETFOCUS” on page 10-83. 


Remarks 

The Language Support Dialog Procedure responds to this message by issuing the 
WinDefDigProc function, then posting a WM_PSETFOCUS message to the application queue 
and setting u/Reserved to the result of the WinDefDigProc function. . 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 


to 0. 


Related Messages 
¢ WM_SETFOCUS 


WM_SIZE (Language Support Dialog) 
For the cause of this message, see “WM_SIZE” on page 10-88. 


For a description of the parameters, see “WM_SIZE” on page 10-88. 


Remarks 

The Language Support Dialog Procedure responds to this message by issuing the 
WinDefDlgProc function, then posting a WM_PSIZE message to the application queue 
andsetting ul/Reserved to the result of the WinDefDlgProc function, 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
¢ WM_SIZE 


WM_SYSCOLORCHANGE (Language Support Dialog) 
For the cause of this message, see “WM_SYSCOLORCHANGE?”’ on page 10-90. 


For a description of the parameters, see “WM_SYSCOLORCHANGE” on page 10-90. 


Remarks ; 

The Language Support Dialog Procedure responds to this message by issuing the 
WinDefDligProc function, then posting a WM_PSYSCOLORCHANGE message to the 
application queue and setting u/Reserved to the result of the WinDefDligProc function. 
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Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 


to 0. 


Related Messages 
¢ WM_SYSCOLORCHANGE 
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Chapter 11. Button Control Window Processing 


This system-provided window procedure processes the actions on a button control 


(WC_BUTTON). 


Purpose 


A button control is a small rectangular child window representing a button that the operator 
can “switch” on or off. Button controls can be used alone or in groups, and can either be 
labeled or appear without text. Button controls typically change appearance when the 
operator clicks a pointing device on them or pressing the space bar when the button has the 


keyboard focus. 


Buttons can be disabled to prevent them from responding when the operator clicks on them. 
Disabled buttons are displayed using a different emphasis technique (for example, color or 


half-toning). 


Button Control Styles 


These button control styles are available: 


BS_AUTOCHECKBOX 
BS_AUTORADIOBUTTON 


BS_AUTOSIZE 


BS_AUTO3STATE 
BS_BITMAP 


BS_CHECKBOX 


BS_DEFAULT 
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An automatic check box automatically toggles its state 
whenever the user clicks on it. 


When clicked, an automatic radio button automatically checks 
itself and unchecks all other radio buttons in the same group. 


Buttons with this style are sized automatically to make sure the 
contents fit. 


lf BS_AUTOSIZE is selected when the button is created, and a 
-1 is specified for either the cx or cy parameter of ; 
WinCreateWindow, (or when creating the button as a resource) 
then the button’s optimal size is calculated to display the its 
contents. 


An automatic three-state check box automatically toggles its 
state when the user clicks on it. 


Places a bit map instead of text on the push button control. 
This style works only with the BS_PUSHBUTTON. 


A check box is a small square with a character string to the 
right. If it is checked, a small black box appears inside the 
small square. When the box or string is clicked, by clicking on 
it with the pointing device or pressing the keyboard spacebar 
when it is active, 


A BS_DEFAULT pushbutton is one with a thick border box. It 
has the same properties as a pushbutton. In addition, the user 
may press a BS_DEFAULT pushbutton by pressing the 
RETURN or ENTER key. The intention is the same for 


BS HELP 


BS_ICON 
BS_MINIICON 


BS_NOBORDER 


BS_NOCURSORSELECT 


BS_NOPOINTERFOCUS 


BS PUSHBUTTON 


BS RADIOBUTTON 


BS_SYSCOMMAND 


user-buttons, but the appearance of a BS_DEFAULT 
userbutton is application defined. 


This style can be ORed with the BS_PUSHBUTTON and 
BS USERBUTTON styles: 


The button posts a WM_HELP message rather than a 
WM_COMMAND message. 


This style can be ORed with the BS_PUSHBUTTON style. 


If both BS_HELP and BS_SYSCOMMAND are set, BS_HELP 
takes precedence. 


Places an icon instead of text on the push button control. This 
style works only with the BS_PUSHBUTTON style. 


This enables miniicons (half the size of normal icons) to be 
placed on the push button control. 


The pushbutton is displayed without a border drawn around it. 
There is no other change in the pushbutton’s operation. 


This style can be ORed with the BS_PUSHBUTTON style. 


The radio button does not select itself when given the focus as 
the result of an arrow key or tab key. 


This style can be ORed with the BS_AUTORADIOBUTTON 
style. 


Buttons with this style do not set the focus to themselves when 
clicked with the pointing device. This enables the cursor to 
stay on a control for which information is required, rather than 
moving to the button. This style has no effect on keyboard 
interaction. The tab key can still be used as usual to move the 
focus to the button. 


This style can be ORed with any of the basic button styles. 


A pushbutton is a box that contains a string. When a button is 
pushed, by clicking the pointing device on it or pressing the 
spacebar when it is active, the parent window is notified. 


A radio button is similar to a check box, but is typically used in 
groups in which only one button at a time is checked. When a 


- radio button is clicked or a cursor key is pressed to move 


within the group, it notifies its owner window. It is then up to 
the owner window to check the clicked radio button and 
uncheck all the rest, if necessary. 


The button posts a WM_SYSCOMMAND message rather than 
a WM_COMMAND message. 


This style can be ORed with the BS_PUSHBUTTON style. 


If both BS_HELP and BS_SYSCOMMAND are set, BS_HELP 
takes 
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BS_TEXT This enables both text and a bitmap, icon, or miniicon to be 
placed on the push button control. This style works only with 
the BS_ PUSHBUTTON style, and should be used in 
conjunction with BS_BITMAP, BS_ICON or BS_MINIICON. 


BS USERBUTTON This is an application-definable button. The owner window of 
this style control receives the additional button style 
BN_PAINT. 

BS 3STATE A three-state check box is identical to a check box control 


except that its check box can be half-toned as well as the box 
being checked or unchecked. 


When BS_ICON, BS_MINIICON or BS_BITMAP is selected, the image can be activated by 
specifying the image ID with the button text string. For instance, to load an icon (#define 
ICON_ID 300), and display it within a button, the button string is set to “#300.” 


When BS_ICON, BS_MINIICON or BS_BITMAP is selected along with BS_TEXT, the image 
can still be activated by specifying the following with a zero-terminated text string. format: 


"#<image-id>\t<text>" 


where: 

<image-id> —_ resource id of the icon, miniicon or bitmap 
\t tab character 

<text> zero-terminated button text string 


For example, to load an icon (#define ICON_ID 300) and display it with the button text “My 
Button,” the button string is set to “#300\tMy Button.” Notice the “\t’ is used to separate the 
text from the image-id. The image is displayed above the text within the button. 


Button Control Data 
See “BTNCDATA’ on page A-24. 


Default Colors 
The following system colors are used when the system draws button controls: 


SYSCLR_BUTTONDEFAULT 
SYSCLR_BUTTONLIGHT 
SYSCLR_BUTTONMIDDLE 
SYSCLR_MENUTEXT 
SYSCLR_WINDOW 
SYSCLR_WINDOWFRAME. 
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Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_BACKGROUNDCOLOR 
PP_BORDERCOLOR 
PP_DISABLEDFOREGROUNDCOLOR 
PP_FOREGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLOR. 
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Button Control Notification Messages 


These messages are initiated by the button control window to notify its owner of significant 
events. 


WM_COMMAND (in Button Controls) 
For the cause of this message, see “WM COMMAND?” on page 10-37. 


For a description of the parameters, see “WWM_COMMAND?” on page 10-37. 


Button control sets uscmd to the button identity and ussource to CADSRC_PUSHBUTTON. 


Remarks 

The button control generates this message when a push button of style BS_PUSHBUTTON 
is pressed or when it receives a BM_CLICK message. The button control posts the 
message to the queue of the control owner. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_COMMAND 


WM_CONTROL (in Button Controls) 
For the cause of this message, see “WM_CONTROL” on page 10-39. 


Parameters 
param? 


id (USHORT) 
Button control identity. 


usnotifycode (USHORT). 
Notification code. 


The notification code BN_PAINT is only generated when the button control has a 
style of BS_USERBUTTON. 


Chapter 11. Button Control Window Processing 11-5 


The button control uses these notification codes: 


BN_CLICKED The button has been pressed. 
BN_DBLCLICKED The button has been double-clicked. 
BN_PAINT The button requires painting, using one of the following draw 
states: 
BDS DISABLED _ The disabled state of the button requires 
painting. 


BDS_HILITED The highlighted state of the button 
requires painting. 

BDS_DEFAULT The default state of the button requires 
painting. 


param2 


flcontrolspec (ULONG) 
Control-specific information. 


When usnotifycode is BN_PAINT this parameter is a pointer to a USERBUTTON 
structure, otherwise this parameter is the window handle of the button control. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The button control generates this message and sends it to its owner, informing the owner of 
this event, when: 


e Its style is not BS_ PUSHBUTTON and the button is pressed. 
e It receives a BM_CLICK message. 
e Its style is BS_USERBUTTON and the button is clicked or double clicked. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_CONTROL 
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WM_HELP (in Button Controls) 
For the cause of this message, see “WM_HELP” on page 10-49. 


For a description of the parameters, see “WM_HELP” on page 10-49. 


Button control sets uscmd to the button identity. 


Remarks 
This message is identical to a WM_COMMAND message, but implies that the application 
should respond to this message by displaying help information. 


The button control generates this message and posts it to the queue of its owner, if it has the 
style of BS_HELP and a push button is pressed, or when it receives a BM_CLICK message. 


Default Processing | 
The default window procedure sends this message to the parent window, if it exists and is 
not the desktop. Otherwise, it sets u/Reserved to 0. 


Related Messages 
e WM_HELP 


WM_SYSCOMMAND 
For the cause of this message, see “WM_SYSCOMMAND?” on page 10-91. 
For a description of the parameters, see “WM_SYSCOMMAND?” on page 10-91. 


Button control sets uscmd to the button identity. 


Remarks 

If the button control is specified with a style of BS_ SYSCOMMAND but not with BS_HELP, 
the button control generates this message and posts it to the queue of its owner when a 
push button is pressed, or when it receives a BM_CLICK message. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 
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Button Control Window Messages 


This section describes the Button Control Window Procedure actions on receiving the 
following messages. 


BM_CLICK 


An application sends this message to cause the effect of the operator clicking a push button. 


Parameters 
param1 


usUp (USHORT) 
Up and down indicator. 


TRUE Perform the default upclick action 
FALSE Perform the default downclick action. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks | 
The button control responds to this message by taking the action that occurs if the button is 
clicked by the operator. This causes the following messages to be generated: 


¢ AWM_HELP (in Button Controls) message, if the button has a style of BS_HELP. 


¢ AWM_SYSCOMMAND message, if the button has a style of BS PUSHBUTTON and a 
style of BS_SYSCOMMAND and not a style of BS_HELP. 


e AWM_COMMAND (in Button Controls) message, if the button has a style of 
BS_PUSHBUTTON but not a style of BS SYSCOMMAND and not a style of BS_HELP. 


¢ AWM_CONTROL (in Button Controls) message, whose usnotifycode is set to 
BN_CLICKED, if the button has a style of BS USERBUTTON, BS_PUSHBUTTON, 
BS_CHECKBOX, or BS_3STATE, and not a style of BS_ SYSCOMMAND or BS_HELP. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set u/Reserved to the default value of 0. 
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BM_QUERYCHECK 


This message returns the checked state of a button control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usCheck (USHORT) 
Check indicator. 


QO The button control is in unchecked state. 
1 The button control is in checked state. 
2 The button control is in indeterminate state. 


Remarks 

The button control responds to this message, if it has a style of BS_CHECKBOX, 
BS_AUTOCHECKBOX, BS_RADIOBUTTON, BS_AUTORADIOBUTTON, BS_3STATE, or 
BS _AUTOS3STATE, by setting usCheck as appropriate. 


If the button has any other style, the button control takes no action other than to set usCheck 
to 0. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set usCheck to the default value of 0. 


BM_QUERYCHECKINDEX 


This message returns the zero-based index of a checked radio button. 


Parameters 
parami 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sindex (SHORT) 
Radio-button index. 


-1 No radio button of the group is checked, or this button control does not have the 
style BS_ RADIOBUTTON or BS_AUTORADIOBUTTON. 
Other Zero-based index of the checked radio button of the group. 


Remarks 
The button control responds to this message by setting s/ndex as appropriate. 


This message may be sent to any radio button or autoradio button in a group of buttons. For 
details of the WS_GROUP style, see “Window Styles” on page 10-3. 


Default Processing 
The default window procedure does not expect to receive this message and etstore takes 
no action on it, other than to set sindex to the default value of 0. 


BM_QUERYHILITE 


This message returns the highlighting state of a button control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Highlight indicator. 


‘TRUE _ The button control is displayed in highlighted state. 
FALSE _ The button control is displayed in unhighlighted state. 


11-10 PM Programming Reference Vol |! 


Remarks 
The button control responds to this message, if it has a style of BS PUSHBUTTON, by 
setting rc as appropriate. 


If the button has any other style, the button control takes no action other than to set rc to 
FALSE. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, except to set rc to the default value of FALSE. 


BM_SETCHECK 


This message sets the checked state of a button control. 


Parameters 
param1 


uscheck (USHORT) 
Check state. 


0 Display the button control in the unchecked state 
1 Display the button control in the checked state 
2 Display a 3-state button control in the indeterminate state. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usoldstate (USHORT) 
Old check state of the button control. 


0 Unchecked 
1 Checked 
2 Indeterminate. 


Remarks 
The button control responds to this message by displaying it in the appropriate state and 
returning the old state. 


If the button control has the style of BS_CHECKBOX, BS_-AUTOCHECKBOX, 
BS_RADIOBUTTON, or BS_AUTORADIOBUTTON, it is displayed in the checked state if 
uscheck is set to 1, or in the unchecked state if it is set to 0 and usoldstate is set as 
appropriate. 
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If the button control has the style of BS_ RADIOBUTTON or BS_AUTORADIOBUTTON, the 
WS_TABSTOP style is modified. If the resulting state of the button is checked, the 
WS_TABSTOP style is set, otherwise it is reset. 


If the button contro! has the style of BS_3STATE or BS_AUTO8STATE, it is displayed in the 
unchecked state if uscheck is set to 0, in the checked state if it is set to 1, and in the 
indeterminate state if it is set to 2 and usoldstate is set as appropriate. 


If the button control has the style of BS_USERBUTTON, a WM_CONTROL (in Button 
Controls) message is sent to its owner with usnotifycode set to BN_PAINT and usoldsiate is 
set as appropriate. 


If the button control has any other style, the button control takes no action other than to set 
usoldstate to 0. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, except to set uso/dstate to the default value of 0. 


BM_SETDEFAULT 


This message sets the default state of a button control. 


Parameters 
param1 


usdefault (USHORT) 
Default state. 


TRUE Display the button control in the default state 
FALSE _ Display the button control in the nondefault state. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful operation 
FALSE _— Error occurred. 
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Remarks 

The button control responds to this message, if it has a style of BS USERBUTTON or 
BS PUSHBUTTON, by displaying the button control in the default or nondefault state as 
appropriate, and setting rc to TRUE. 


If the button control has any other style, the button control takes no action other than to set 
rc to FALSE. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


BM_SETHILITE 


This message sets the highlight state of a button control. 


Parameters 
param1 


ushilite (USHORT) 
Highlight indicator. 


TRUE Display the button control in the highlighted state 
FALSE _ Display the button control in the unhighlighted state. 


param2 


ulReserved (ULONG) . 
Reserved value, should be 0. 


Returns 
foldstate (BOOL) 
Old highlight state. 


TRUE _ The button control was in highlighted state 
FALSE The button control was in unhighlighted state. 


Remarks 

The button control responds to this message, if it has a style of BS PUSHBUTTON, 

BS_ CHECKBOX, BS_AUTOCHECKBOX, BS_RADIOBUTTON, BS_AUTORADIOBUTTON, 
BS_3STATE, or BS_AUTOSSTATE, by displaying the button control in the appropriate 
highlight state and setting foldstate as appropriate. 


If the style of the Button Control is BS_USERBUTTON, a WM_CONTROL (in Button 
Controls) message is sent to its owner with usnotifycode set to BN_PAINT and with 
ficontrolspec pointing to a USERBUTTON structure and sets foldstate as appropriate. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set foldstate to the default value of FALSE. 


WM_ENABLE (in Button Controls) 
For the cause of this message, see “WM_ENABLE” on page 10-43. 


For a description of the parameters, see “WM_ENABLE” on page 10-43. 


Remarks 
This message notifies the button contro! window procedure of a change in the enable state of 
the button. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM _ENABLE 


WM_MATCHMNEMONIC (in Button Controls) 
For the cause of this message, see “WM_MATCHMNEMONIC” on page 10-55. 


For a description of the parameters, see “WM_MATCHMNEMONIC’ on page 10-55. 


Remarks 
The button control window procedure responds to this message by setting rc as appropriate. 
If MP1 matches the button mnemonic, return rc to TRUE. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
© WM_MATCHMNEMONIC 
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WM_QUERYCONVERTPOS (in Button Controls) 
For the cause of this message, see “WM_QUERYCONVERTPOS’ on page 10-72. 


For a description of the parameters, see “WM _QUERYCONVERTPOS’ on page 10-72. 


Remarks 
The button control window procedure returns QCP_NOCONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS’ on page 10-72. 


Related Messages 
¢ WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in Button Controls) 


Occurs when an application queries the button control window procedure window 
parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Remarks 
The button control window procedure responds to this message by passing it to the default 
window procedure. 


Default Processing 

The default window procedure sets the cchText, cbPresParams, and cbCtiData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to zero and sets rc to 
FALSE. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 


WM_SETWINDOWPARAMS (in Button Controls) 


Occurs when an application sets or changes the button control window procedure window 
parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS?’ on page 10-86. 


Remarks 
The button control window procedure responds to this message by passing it to the default 
window procedure. 
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Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_SETWINDOWPARAMS 
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Chapter 12. Entry Field Control Window Processing 


This system-provided window procedure processes the actions on an entry field control 


(WC_ENTRYFIELD). 


Purpose 


An entry field control is a rectangular window that displays a single line of text that the 
operator can edit. When it has the focus, the cursor marks the current insertion or 


replacement point. 


When working with entry fields, the WM_CONTROL message is of major concern. An 
entry-field control communicates with its owner by sending WM_CONTROL messages. It 
contains a notification code in MP1 and a handle to the current entry field in MP2. The 
return value for WM_CONTROL is 0. Notification codes are denoted by an EN prefix. 


Entry Field Control Styles 


These entry field control styles are available: 


ES LEFT 


ES RIGHT 

ES CENTER 

ES AUTOSIZE 

ES AUTOSCROLL 


ES MARGIN 


ES READONLY 
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The text in the control is left-justified. This is the default style if 
neither ES_RIGHT nor ES_CENTER is specified. 


The text in the control is right-justified. 
The text in the control is centered. 
The text will be sized to make sure the contents fit. 


If the user tries to move off the end of a line, the control 
automatically scrolls one-third the width of the window in the 
appropriate direction. 


This style can be used to cause a border to be drawn around the 
control, with a margin around the editable text. The margin is half a 
character-width wide and half a character-height high. 


When an entry field control with this style is positioned, it adjusts the 
position so that the text is placed at the position specified. This 
position differs from the original position by the width of the border 
and the margin. 


This style causes a single line entry field to be created in read only 
state. 


When an entry field is in read only state, characters do not get 
inserted into the text. However the insertion interface is still 
functional. 


The entry field read only state can be altered by use of the 
EM_SETREADONLY message. 
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ES UNREADABLE This style causes the text to be displayed as an asterisk for each 
character. It can be used for passwords. 


ES COMMAND This style identifies the entry field as a command entry field. This 
information is used by the Help Manager to provide command help if 
the end user requests help for this field. 


Not more than one entry field on each dialog should be given this 
style. 


ES AUTOTAB This style indicates that when the field is filled by adding a character 
to the end of the entry field text, the effect of a tab key will be 
generated. Inserting or replacing a character in the middle of the 
text, however, does not result in an autotab. 


This style is recommended for use with fixed-length, non-scrollable 
fields that are filled completely. The maximum length of the entry 
field text is held in the control data, see “Entry Field Control Data” on 
page 12-3 


These entry field controls are intended for countries that use a double-byte character 
encoding scheme: 


ES SBCS The text is purely single-byte. 


If the number of characters entered exceeds EM_SETTEXTLIMIT, or 
a DBCS character is entered, the alarm sounds and the last 
character entered is ignored. 


ES DBCS The text is purely double byte. 


If the number of bytes in the entry field exceeds EM_SETTEXTLIMIT, 
or an SBCS character is entered, the alarm sounds and the last 
character entered is ignored. 


ES ANY The text is a mixture of SBCS and DBCS characters. 


If the number of bytes in the input field exceeds EM_SETTEXTLIMIT, 
the alarm sounds and the last character entered is ignored. 


ES_ANY is the default. 


Note: If the queue code page is an ASCII code page and the data 
in the entry field is to be converted to an EBCDIC code page, 
there is a possibility that shift-in and shift-out characters 
introduced by the conversion process can cause the 
converted data to overrun the target field. Coding ES_MIXED 
protects the target field from overrun in this situation. 


ES MIXED The text is a mixture of SBCS and DBCS characters which may 
subsequently be converted from an ASCII DBCS code page to an 
EBCDIC DBCS code page with a consequent possible increase in 
the length of the data. 


if 
DBCSchars*2 + SBCSchars + N > EM SETTEXTLIMIT 
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where N starts at 0 and is incremented whenever the string goes 
from SBCS to DBCS or DBCS to SBCS, the alarm sounds and the 
last character entered is ignored. 


Note: For every conversion from SBCS to DBCS there must be a 
corresponding return to SBCS (N must be an even number). 


Entry Field Control Data 
See “ENTRYFDATA’ on page A-64. 


Default Colors 
The following system colors are used when the system draws button controls: 


SYSCLR_ENTRYFIELD 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONLIGHT 
SYSCLR_OUTPUTTEXT 
SYSCLR_WINDOWTEXT 
SYSCLR_HIGHLITEFOREGROUND 
SYSCLR_HIGHLITEBACKGROUND 


Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_FOREGROUNDCOLOR 
PP_DISABLEDFOREGROUNDCOLOR 
PP_HIGHLIGHTFOREGROUNDCOLOR 
PP_FONTNAMESIZE 
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Entry Field Control Notification Messages 


This message is initiated by the entry field control window to notify its owner of significant 
events. 


WM_CONTROL (in Entry Fields) 
For the cause of this message, see “WM CONTROL’ on page 10-39. 


Parameters 
param1 


id (USHORT) 
Control window identity. 


usnotifycode (USHORT) 
Notify code. 


-EN_CHANGE The content of the entry field control has changed, and the 
change has been displayed on the screen. 


EN_KILLFOCUS _ The entry field control is losing the focus. 


EN.MEMERROR The entry field control cannot allocate the storage necessary to 
accommodate window text of the length implied by the 
EM_SETTEXTLIMIT message. 


EN OVERFLOW The entry field control cannot insert more text than the current 
text limit. The text limit may be changed with the 
EM_SETTEXTLIMIT message. 


If the recipient of this message returns TRUE, then the entry 
field control retries the operation, otherwise it terminates the 
operation. 


EN_ SCROLL The entry field control is about to scroll horizontally. This can 
happen in these circumstances: 


The application has issued a WinScrollWindow call 
The content of the entry field control has changed 
The caret has moved 

The entry field control must scroll to show the caret 
position. 


EN_SETFOCUS _ The entry field control is receiving the focus. 


param2 


hwndcontrolspec (HWND) 
Entry field contro! window handle. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The entry field control window procedure generates this message and sends it to its owner, 


informing the owner of the event. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
¢ WM_CONTROL 
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Entry Field Control Window Messages 


This section describes the entry field control window procedure actions on receiving these 
messages: 


EM_CLEAR 


This message deletes the text that forms the current selection. 


Parameters 
parami 


ulReserve (ULONG) 
Reserved value, should be 0. 


param2 


ulReserve (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE — Successful completion 
FALSE _ Error occurred. 


Remarks 
The entry field control window procedure responds to this message by deleting the text that 
forms the current selection and setting usmaxsel equal to usminsel. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_COPY 


This message copies the current selection to the clipboard. 


Parameters 
param 


ulReserved (ULONG) 
Reserved value, shouid be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE _ Error occurred. 


Remarks 
The entry field control window procedure responds to this message by copying the text that 
forms the current selection to the clipboard in CF_TEXT format. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_CUT 


This message copies the text that forms the current selection to the clipboard, and then 
deletes it from the entry field control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 
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Remarks 

The entry field control window procedure responds to this message by copying the text that 
forms the current selection to the clipboard in CF_TEXT format, and then deleting it from the 
entry field control and setting usmaxsel equal to usminsel. 


This message is the combination of a EM_COPY message followed by a EM_CLEAR 
message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM PASTE 


This message replaces the text that forms the current selection with text from the clipboard. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE = Successful completion 
FALSE _ Error occurred. 


For example, if the text to be inserted does not fit in the entry field control 
without overflowing the text limit set by the EM_SETTEXTLIMIT message, in 
which instance no text is inserted. | 


Remarks 
The entry field control window procedure responds to this message by replacing the text that 
forms the current selection with text from the clipboard, if the data is in CF_TEXT format. 


Only characters from the clipboard up to the first carriage return are used in the replacement. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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EM_QUERYCHANGED 
This message enquires if the text of the entry field control has been changed since the last 
enquiry. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Changed indicator. 


TRUE The text in the entry field control has been changed since the last time it 
received this message or a WM_QUERYWINDOWPARAMS message. 


FALSE _ All other situations. 


Remarks 

The entry field control window procedure responds to this message by setting rc to indicate 
whether the text of the entry field has been changed since the last time either this message 
or a WM_QUERYWINDOWPARAMS (in Entry Fields) message has been received. 


Default Processing ° 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_QUERYFIRSTCHAR 
This message returns the zero-based offset of the first character visible at the left edge of an 
entry-field control. ea 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sOffset (SHORT) 
Zero-based offset. 


Remarks 


The entry field control window procedure responds to this message by returning the 
zero-based offset into the text that corresponds to the first character displayed in the entry 


field control. 


Default Processing 


The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sOffset to the default value of 0. 


EM_QUERYREADONLY 


This message returns the read only state of an entry field control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Read only state indicator. 


TRUE Read only state is enabled. 
FALSE Read only state is disabled. 


Remarks 


The entry field control window procedure responds to this message by returning the read 


only state of the entry field control. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_QUERYSEL 
This message gets the zero-based offsets of the bounds of the text that forms the current 
selection. ; 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


sMinSel (SHORT) 
Offset of the first character in the selection. 


sMaxSel (SHORT) 
Offset of the first character after the selection. 


Remarks 
The entry field control window procedure responds to this message by returning the 
zero-based offsets of the bounds of the text that forms the current selection. 


Default Processing 

The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sMinSel to the default value of 0, which is equivalent to 
setting both sMinSe/ and sMaxSel to 0. 
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EM_SETFIRSTCHAR 


This message specifies the offset of the character to be displayed in the first position of the 
entry field control. 


Parameters 
param1 


sOffset (SHORT) 
Zero-based offset of the first character to be displayed. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE ~— Successful completion 
FALSE Error occurred. For example, because sOftset i is not valid. 


Remarks 

The entry field control window procedure responds to this message by setting the text 
displayed in the edit control so that the first character displayed on the left of the window has 
the zero-based index specified by sOffset. 


An EN_SCROLL notification message occurs, if the entry field control scrolls. This message 
returns FALSE if the edit control does not have the ES AUTOSCROLL style or it is center of 
right justified. 


Default Processing : 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


12-12 PM Programming Reference Vol II 


EM_SETINSERTMODE 


This message sets the insert mode of an entry field. 


Parameters 
param1 


usinsert (USHORT) 
Insert mode indicator. 


TRUE Enable insert mode. 
FALSE Enable overtype mode. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Previous insert mode indicator. 


TRUE Insert mode was previously enabled. 
FALSE Overtype mode was previously enabled. 


Remarks 

The entry field control window procedure responds to this message by setting the insert 
mode of the entry field, updating the SV_INSERTMODE system constant and redrawing the 
entry field. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_SETREADONLY 


This message sets the read only state of an entry field control. 


Parameters 
param1 


usReadOnly (USHORT) 
Read only state indicator. 


TRUE Enable read only state 
FALSE _ Disable read only state. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Previous read only state indicator. 


TRUE Read only state was previously enabled. 
FALSE Read only state was previously disabled. 


Remarks 
The entry field control window procedure responds to this message by setting the read only 
state of the entry field control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_SETSEL 


This message sets the zero-based offsets of the bounds of the text that forms the current 
selection. 


Parameters 
param1 


usminsel (USHORT) 
Offset of the first character in the selection. 


usmaxsel (USHORT) 
Offset of the first character after the selection. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


. TRUE — Successful completion 
FALSE — Error occurred. 
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Remarks 
The entry field control window procedure responds to this message by setting the zero-based 
offsets of the bounds of the text that forms the current selection. 


If usminsel equals usmaxsel, the current selection becomes an insertion point. 


If usminsel equals 0 and usmaxsel is equal to or greater than the text limit set by the 
EM_SETTEXTLIMIT message, the entire text is selected. Selected text is displayed in 
reverse color. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


EM_SETTEXTLIMIT 


This message sets the maximum number of bytes that an entry field control can contain. 


Parameters 
param1 


sTextLimit (SHORT) 
Maximum number of characters in the entry field control. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE Error occurred. For example, because not enough storage can be allocated. 


Remarks 
The entry field control window procedure responds to this message by setting the maximum 
number of characters that can be contained. 


This message is intended only to limit the length of lines that result from the user interacting 


with the entry field control. It also limits the length of text that can result from sending a 
EM_PASTE or WM_SETWINDOWPARAMS message. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


WM_CHAR (in Entry Fields) 
For the cause of this message, see “WM_CHAR’” on page 10-32. 


For a description of the parameters, see “WWM_CHAR?’ on page 10-32. 


Remarks 

The entry field control window procedure responds to this message by sending it to its owner 
if it has not processed the keystroke. This is the most common means by which the input 
focus is switched around the various controls in a dialog box. 


Unlike other controls, the usvk field of the message “WM_CHAR” on page 10-32 takes 
precedence over other fields only when the Shift key is pressed. 


If this message contains a valid usch field of the message “WM_CHAR’ on page 10-32. that 
character is entered into the text in insert or overtype mode. 


The keystrokes processed by an entry field control are: 


Left arrow Move the cursor one character to the left. 

Right arrow Move the cursor one character to the right. 

Shift+Left arrow Extend the selection by one character to the left. 

Shift+Right arrow Extend the selection by one character to the right. 

Home Move the cursor to the beginning of the text. 

End Move the cursor to the end of the text. 

Backspace Delete the character to the left of the cursor.., 

Delete When the selection is an insertion point, delete the character to the 


right of the cursor, otherwise delete the current selection, but do not 
put it in the clipboard. 


Shift+Del Cut the current selection to the clipboard. 

Shift+Ins Replace the current selection with the text contents from the 
clipboard. 

Ctrl+Del ~ Delete to the end of the field. 

Ctri+iIns Copy the current selection to the clipboard. 


If the control contains more text than can be shown, the actions defined above that move the 
cursor cause the text to be scrolled. The amount of scrolling varies from key to key, and the 
position of the text within the control varies for the same cursor position. 


Default Processing 
The default window procedure sends the message to the owner window if it exists, otherwise 
it takes no action on this message other than to set re to FALSE. 
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Related Messages 
¢ WM_CHAR 


WM_QUERYCONVERTPOS (in Entry Fields) 
For the cause of this message, see “WM_QUERYCONVERTPOS’ on page 10-72. 


For a description of the parameters, see “WM _QUERYCONVERTPOS’ on page 10-72. 


Remarks 
The entry field control window procedure updates pCursorPos to the position of the cursor 
and returns QCP_CONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS?’ on page 10-72. 


Related Messages 
e WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in Entry Fields) 


This message occurs when an application queries the entry field control window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Remarks 

The entry field control window procedure responds to this message by returning the window 
parameters indicated by the fsStatus parameter of the WNDPARAMS data structure 
identified by the pwndparams parameter. 


Default Processing 
The default window procedure sets the cchText, cbPresParams, and cbCtiData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to 0 and sets rc to FALSE. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 
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WM_SETWINDOWPARANS (in Entry Fields) 


This message occurs when an application sets or changes the entry field control window 
parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS?’ on page 10-86. 


Remarks 

The entry field contro! window procedure responds to this message by setting the window 
parameters indicated by the fsStatus parameter of the WNDPARAMS data structure, 
identified by the pwndparams parameter. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_SETWINDOWPARAMS 
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Chapter 13. Frame Control Window Processing 


This system-provided window procedure processes the actions on a frame window 
(WC_FRAME). The frame control window procedure sends all messages not processed to 
FID_CLIENT and sets reply to 0. 


Purpose 
The window that contains all of the parts listed below is called the frame window. Each of 
the parts that make up a window, such as ‘the title bar and menu, are separate child windows 
of the frame window. All of these child windows, except the client window (FID_CLIENT), 
are called frame controls. 


FID_CLIENT is not a frame control, it is an instance of a window class implemented by the 
application. 


The frame window and all of the frame controls are implemented with system-provided 
preregistered window classes. 


The frame window holds together all of the frame controis and FID_CLIENT that make up an 
application window. The frame window is responsible for arranging the frame controls and 
the FID_CLIENT as the frame window is sized and moved. It is also responsible for routing 
specific messages to its frame controls and the FID_CLIENT. 


Each of the frame controls and FID_CLIENT are known to the frame window by a 
system-provided window-identifier value as listed below: . 


FID_CLIENT Client window 
FID_HORZSCROLL ~ Horizontal scroll bar 
FID_MENU Application menu 
FID_MINMAX Minimize/Maximize box 
FID_SYSMENU System menu 
FID_TITLEBAR Title bar 


FID_VERTSCROLL _ Vertical scroll bar. 
For correct operation, only one window per frame must be defined with each of the above 


FID_* values. 


Frame Creation Flags 


These frame creation flags are available: 


FCF_TITLEBAR Title bar. 

FCF_SYSMENU System menu. 

FCF_MENU Application menu. 
FCF_MINMAX Minimize and Maximize buttons. 
FCF_MiINBUTTON Minimize button. 
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FCF_MAXBUTTON 
FCF_VERTSCROLL 
FCF_HORZSCROLL 
FCF_SIZEBORDER 
FCF_BORDER 
FCF_DLGBORDER 
FCF_ACCELTABLE 


FCF_ICON 


FCF_SHELLPOSITION 


FCF_SYSMODAL 
FCF_NOBYTEALIGN 


FCF_TASKLIST 


FCF_NOMOVEWITHOWNER 
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Maximize button. 

Vertical scroll bar. 

Horizontal scroll bar. 

Sizing border. 

Window is drawn with a thin border. 

Window is drawn with a standard dialog border. 


Causes an accelerator table to be loaded, for this frame 
window, from the resource file identified on the 
WinCreateStdWindow function. 


Window is created with an icon associated with it that is 
used to represent the window when it is minimized. 


If present, the Resource parameter of the 
WinCreateStdWindow function must be the identity of an 
icon. This icon is loaded and associated with the window. 
When the window is minimized, the icon is shown if the 
screen is capable of showing it. When the window is 
destroyed, the icon is also destroyed. . 


The window is created with a size and position determined 
by the shell, rather than explicitly by the application. 


The frame window is System Modal. 


When this flag is not set, the frame window is adjusted so 
that window operations, such as moving, can be 
performed in an optimized manner. For example, some 
displays can move a window more quickly if the 
movement is by a multiple of eight pels. 


If this flag is set, such optimizations are not performed and 
size and position values are honored. 


When this flag is set, the program title is added to the 
front of the frame window text, the resulting string is used 
as the window title and is also entered on the task list. 


In this context, the program title is the text string used by 
the Desktop Manager to identify the program, or the text 
string specified as a parameter in the START command. If 
neither string has been defined, the filename and 
extension of the .EXE file are used as the program title. 


Note that a WinSetWindowText will not change the entry 
in the switch list, a WinChangeSwitchEntry must be done 
to affect this. 


The window should not be moved when its owner is 
moved. 


FCF_STANDARD 


FCF_SCREENALIGN 
FCF_MOUSEALIGN 
FCF_AUTOICON 


FCF_HIDEBUTTON 
FCF_HIDEMAX 


Frame Control Styles 


Same as (FCF_TITLEBAR | FCF_SYSMENU | 
FCF_MINBUTTON | FCF_MAXBUTTON | 
FCF_SIZEBORDER | FCF_ICON | FCF_MENU | 
FCF_ACCELTABLE | FCF_SHELLPOSITION | 
FCF_TASKLIST). 


This value is assumed if any Frame Window is created 
with no Control Data. 


See FS_SCREENALIGN. 
See FS_MOUSEALIGN. 


Performance optimization. When repainting iconized 
frames, the system will redraw the icon and will not send a 
WM_PAINT message to the application. 


Hide button. 


Hide and maximize buttons. 


These frame control styles are available. Frame styles may omy be used when the frame is 


created from a dialog template. 
FS_SCREENALIGN 


FS _MOUSEALIGN 


FS SIZEBORDER 

FS_ BORDER 
FS_DLGBORDER 
FS_SYSMODAL 

FS NOBYTEALIGN 
FS_TASKLIST 
FS_NOMOVEWITHOWNER 
FS _AUTOICON 


Frame Control Data 


The coordinates specifying the location of the dialog box 
are relative to the top left corner of the screen, rather than 
being relative to the owner window’s origin. 


The coordinates specifying the location of the dialog box 
are relative to the position of the pointing device pointer at 
the time the window was created. The operating system 
tries to keep the dialog box on the screen, if possible. 


See FCF_SIZEBORDER. 

See FCF_BORDER. 

See FCF_DLGBORDER. 

See FCF_SYSMODAL. 

See FCF_NOBYTEALIGN. 

See FCF_TASKLIST. 

See FCF_NOMOVEWITHOWNER. 
See FCF_AUTOICON. 


See “FRAMECDATA’” on page A-99. 
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Default Colors 
The following system colors are used when the system draws button controls: 


SYSCLR_DIALOGBACKGROUND 
SYSCLR_ACTIVETITLE 
SYSCLR_INACTIVETITLE 
SYSCLR_APPWORKSPACE 
SYSCLR_ACTIVEBORDER 
SYSCLR_WINDOW 
SYSCLR_SHADOW 
SYSCLR_WINDOWFRAME 
SYSCLR_FIRST. 


Some of these defaults can be replaced by using the following presentation parameters in 


the application resource script file or source code: 


PP_BACKGROUNDCOLOR 
PP_SHADOW 
PP_FOREGROUNDCOLOR 
PP_BORDERCOLOR 
PP_DISABLEDBACKGROUNDCOLOR. 
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Frame Control Notification Messages 
These messages are initiated by the frame control window to notify the FID _CLIENT window. 


WM_MINMAXFRAME (in Frame Controls) 
For the cause of this message, see “WM_MINMAXFRAME” on page 10-58. 


For a description of the parameters, see “WM_MINMAXFRAME” on page 10-58. 


Remarks 

The window words QWS_XRESTORE, QWS_YRESTORE, QWS_CXRESTORE, and 
QWS_CYRESTORE for hwnd are initialized before this message is sent. The window state 
has not been changed when this message is sent, and so the WinQueryWindowPos function 
can be used. 


This message is sent by default to the FID_CLIENT window. 


The system default actions, if FALSE is returned to this message, are based on the 
operation specified by the pswp parameter. 


These actions affect the status of the frame window, and the title button windows and system 
menu windows contained within it, as follows: 
e Window is maximized from a minimized state. 
— Title button windows: 


The RESTORE button window is replaced by a MIN button window and the MAX 
button window is replaced by a RESTORE button window. 


— System menu window: 
The MINIMIZE menu entry is enabled and the MAXIMIZE menu entry is disabled. 
— Other changes: 


The frame window has the WS_MAXIMIZED style bit set and the WS_MINIMIZED 
style bit reset. Also the MS_VERTICALFLIP style bit of the system menu window is 
reset. 


e Window is restored from a minimized state. 
— Title button windows: 


The RESTORE button window is replaced by a MIN button window (the MAX button 
window is unaltered). 


— System menu window: 


The MINIMIZE menu entry is enabled, the RESTORE menu entry is disabled and 
the SIZE menu entry is enabled. 
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— Other changes: 


The frame window has the WS_MINIMIZED style bit and the MS_VERTICALFLIP 
style bit of the system menu window reset. 


Window is minimized from a maximized state. 


— Title button windows: 


The RESTORE button window is replaced by a MAX button window and the MIN 
button window is replaced by a RESTORE button window. 


System menu window: 
The MAXIMIZE menu entry is enabled and the MINIMIZE menu entry is disabled. 
Other changes: 


The frame window has the WS_MINIMIZED style bit set and the WS_MAXIMIZED 
style bit reset. Also the MS_VERTICALFLIP style bit of the system menu window is 
set. 


e Window is restored from a maximized state. 


— Title button windows: 


The RESTORE button window is replaced by a MAX button window (the MIN button 
window is unaltered). 


System menu window: 


The MAXIMIZE menu entry is enabled, the RESTORE menu entry is disabled and 
the SIZE menu entry is enabled. 


Other changes: 
The frame window has the WS_MAXIMIZED style bit reset. 


Window is minimized from a restored state. 


— Title-button windows: 


The MIN button window is replaced by a RESTORE button window (the MAX button 
window is unaltered). 


System menu window: 


The RESTORE menu entry is enabled, the MINIMIZE menu entry is disabled and 
the SIZE menu entry is disabled. 


Other changes: 


The frame window has the WS_MINIMIZED style bit set, and the 
MS_VERTICALFLIP style bit of the system menu window is set. 
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e Window is maximized from a restored state. 
— Title-button windows: 


The MAX button window is replaced with a RESTORE button window (the MIN 
button window is unaltered). 


— System menu window: 

The RESTORE menu entry is enabled, the MAXIMIZE menu entry is disabled. 
— Other changes: 

The frame window has the WS_MAXIMIZED style bit set. 


Default Processing 


The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_MINMAXFRAME 
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Frame Control Window Messages 


This section describes the frame control window procedure actions on receiving the following 
messages. 


WM_ACTIVATE (in Frame Controls) 
For the cause of this message, see “WM_ACTIVATE” on page 10-5. 


For a description of the parameters, see “WWM_ACTIVATE” on page 10-5. 


Remarks 

The frame control window procedure responds to this message by first sending a 
TBM_SETHILITE message to the FID_TITLEBAR control, if it exists, to highlight or 
unhighlight the title bar. If the style is FCF_DLGBORDER, the border is redrawn in either 
highlighted or unhighlighted state, as necessary. 


It then sends the WM_ACTIVATE message to the FID_CLIENT window. 


Then it sets u/Reserved to 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. ; 


Related Messages 
¢ WM_ACTIVATE 


WM_ADJUSTFRAMEPOS 


This message is sent to a frame window whose position or size is to be adjusted. 


Parameters 
param1 | 


pswp (PSWP) 
New frame window state. 


This points to a SWP structure. 


The structure has been filled in by the WinSetWindowPos or WinSetMultWindowPos 
functions with the proposed move or size data for the frame window. 


param2 


hsavewphsvwp (HSAVEWP) 
Identifier of the frame window repositioning process. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

When a WinSetWindowPos or WinSetMultWindowPos function involves adjusting the position 
or size of a frame window, a WM_ADJUSTFRAMEPOS message is sent to the frame 
window. 


The frame control processes the message by informing all the windows in its owner 
hierarchy, that is all the windows owned by the frame and all the windows owned by them 
and so on, by sending each a WM_OWNERPOSCHANGE message. Each window receiving 
the a WM_OWNERPOSCHANGE message is expected to modify the SWP structure 
provided as the first parameter in the message to the appropriate values relative to the new 
position and/or size of its owner, whose new position and size is specified in a SWP | 
structure provided as the second parameter in the message. 


In this way the frame control can determine the state changes to be made to all the windows 
in its owner hierarchy, in accordance with the values specified in the SWP structure 
referenced by the pswp parameter. The rules for changing the state of these owned 
windows are: 


SWP_SIZE and SWP_MOVE 
The owned window is moved relative to the top left corner of its owner. 


SWP_SHOW 
The visibility state of an owned window is changed to agree with that of their owner. 


SWP_MINIMIZE 
An owned window is made invisible when the owner is minimized. 


SWP_MAXIMIZE and SWP_RESTORE 
An owned window that was previously made invisible when the owner was minimized 
is made visible. 


The frame window coordinates the repositioning of the frame window and all its owned 
windows, by using the WinSaveWindowPos function to associate those windows whose 
states are to change with the identifier of the frame window repositioning process, that is the 
hsavewphsvwp parameter. Eventually, the state changes to be made to the owned windows 
are contained in the array of SWP structures identified by the pswp parameter. 


lf the frame window is subclassed, this message must then be passed to the superclass 
window procedure for processing. The superclass window procedure is the window 
procedure of the window before it was subclassed. This message is passed along the chain 
of window procedures and is eventually processed by the system frame window procedure. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 
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WM_BUTTON1DBLCLK (in Frame Controls) 
For the cause of this message, see “WM_BUTTON1DBLCLK’ on page 10-12. 


For a description of the parameters, see “WM_BUTTON1DBLCLK’” on page 10-12. 


Default Processing 

If the frame is minimized, the frame control window procedure causes the frame window to 
return to its previous state. Otherwise, the message is handled like a WM_BUTTON1DOWN 
message. 


Related Messages 
¢ WM_BUTTON1DBLCLK 


WM_BUTTON2DBLCLK (in Frame Controls) 
For the cause of this message, see “WM_BUTTON2DBLCLK’” on page 10-18. 


For a description of the parameters, see “WM_BUTTON2DBLCLK’” on page 10-18. 


Default Processing 
The frame control window procedure processes this message identically to 
WM_BUTTON1DBLCLK (in Frame Controls). 


Related Messages 
¢ WM_BUTTON2DBLCLK 


WM_BUTTON1DOWN (in Frame Controls) 
For the cause of this message, see “WM_BUTTON1DOWN?” on page 10-13. 


For a description of the parameters, see “WM_BUTTON1DOWN” on page 10-13. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer button information. 


Default Processing 

The frame control window procedure responds to this message by issuing the 
WinSetActiveWindow function and sets rc to TRUE. If this is over a part of the window that 
does not have a frame control, it issues a WinSetActiveWindow function. If the click is over 
the size border, this window begins tracking by sending a WM_TRACKFRAME message to 
itself. lf the click is not over the size border, this message is passed on. 


Related Messages 
°¢ WM_BUTTONIDOWN 
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WM_BUTTON2DOWN (in Frame Controls) 
For the cause of this message, see “WM_BUTTON2DOWN’” on page 10-19. 


For a description of the parameters, see “WM_BUTTON2DOWN” on page 10-19. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer button information. 


Default Processing 
The frame control window procedure processes this message identically to 
“WM_BUTTON1DOWN (in Frame Controls)” on page 13-10. 


Related Messages 
e WM_BUTTON2DOWN 


WM_BUTTON1UP (in Frame Controls) 
For the cause of this message, see “WM_BUTTON1UP” on page 10-16. 


For a description of the parameters, see “WM _BUTTON1UP” on page 10-16. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer button information. 


Default Processing 

The frame control window procedure responds to this message by issuing the 
WinSetActiveWindow function and sets rc to TRUE. If the window is not minimized, this 
message is not processed. If the frame is minimized, this message causes the system menu 


to pop up. 


Related Messages 
e WM_BUTTON1UP 
WM_BUTTON2UP (in Frame Controls) 
For the cause of this message, see “WM_BUTTON2UP” on page 10-22. 


For a description of the parameters, see “WM_BUTTON2UP’” on page 10-22. 


Remarks 
This message is posted to the application queue associated with the window that is to 
receive the pointer button information. 
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Default Processing 
The frame control window procedure processes this message identically to 
“WM_BUTTON1UP (in Frame Controls)” on page 13-11. 


Related Messages 
¢ WM_BUTTON2UP 


WM_CALCFRAMERECT (in Frame Controls) 
For the cause of this message, see “WM_CALCFRAMERECT” on page 10-29. 


For a description of the parameters, see “WM_CALCFRAMERECT” on page 10-29. 


Remarks 
Frame control calculates the appropriate rectangle, taking into account byte alignment, or 
nonbyte alignment if FCF_NOBYTEALIGN is specified. 


Default Processing 


The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_CALCFRAMERECT 


WM_CHAR (in Frame Controls) 


This message is sent by controls to their owner window if they do not process the key stroke 
themselves. It is the most common means by which the input focus is switched around the 
various controls in a dialog box. 


For a description of the parameters, see “WM_CHAR?’” on page 10-32. 


Default Processing 
The frame control window procedure responds to this message as follows: 


¢ If the message contains a valid VK_ value, that value is processed before any valid 
character in the message. 


e lf the character matches a mnemonic in the text of a button or static control child 
window, the focus is set to that window. 


e {f the character is Tab or Backtab, the focus is set to the next or previous tabstop 
window. 


e If the character is Up or Left Arrow, the focus is set to the previous item in the group. 


e If the character is Down or Right Arrow, the focus is set to: the next item in the group. 
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e If the Enter key is pressed, a WM_COMMAND message is posted to itself, containing 
the identity of the button with the focus, or, if none, the identity of the default push 
button. 


e If the Escape key is pressed, a WM_COMMAND message is posted to itself with the 
command value DID_CANCEL. 


Related Messages 
* WM_CHAR 


WM_CLOSE (in Frame Controls) 
For the cause of this message, see “WM_CLOSE” on page 10-35. 


For a description of the parameters, see “WM_CLOSE” on page 10-35. 


Remarks 
Frame control sends this message to the client window (FID_CLIENT) if it exists, otherwise it 
cails the WinDefWindowProc function. 


Default Processing 
The default window procedure posts a WM_QUIT message to the appropriate queue and 
sets u/Reserved to 0. 


Related Messages 
¢ WM_CLOSE 


WM_COMMAND 
For the cause of this message, see “WWM_COMMAND?” on page 10-37. 


For a description of the parameters, see “WM_COMMAND?” on page 10-37. 


Default Processing 
The Frame Control window procedure responds to this message by sending it the client 
window if it exists, otherwise the message is thrown away. 


WM_DRAWITEM (in Frame Controls) 
For the cause of this message, see “WM_DRAWITEM’” on page 10-42. 


For a description of the parameters, see “WM_DRAWITEM?” on page 10-42. 


Remarks 
The identity of the top-level action-bar menu that generated this message is found. If the 
identity is FID_ MENU, the message is passed to the window with identity FID_CLIENT. 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
e WM_DRAWITEM 


WM_ERASEBACKGROUND 


This message causes a client window to be filled with the background, should this be 
appropriate. 


Parameters 
param1 


hpsFrame (HPS) 
Presentation-space handle for the frame window. 


param2 


pprePaint (PRECTL) 
Rectangle structure of rectangle to be painted. 


This points to a RECTL structure. 


Returns 
re (BOOL) 
Processed indicator. 


TRUE ~~ If a FID_CLIENT window exists, the area of the frame covered by the 
FID_CLIENT window is erased in the system-window background color. 


If no FID_CLIENT window exists, the entire frame window is erased in the 
system-window background color. 


FALSE The client window did process the message. 


Remarks 
The frame window procedure processes this message in the following manner: 


1. The frame window sends this message to the client in response to the frame 
WM_PAINT message, with the presentation-space handle of the frame window (obtained 
from WinBeginPaint). 


2. If the client window returns TRUE, the frame window procedure erases the rectangle of 
the frame window covered by the client window, by filling it with the system color 
SCLR_WINDOW. . 


3. If the client window returns FALSE, no action is taken. This is the default behavior, as 
~WinDefWindowProc returns FALSE if passed this message. 
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4. Also, the client window can use the presentation-space handle passed in this message 
to selectively erase parts of the screen. If the client window processes the message in 
this way, FALSE should be returned to avoid the erasure being done automatically by 
the frame window procedure. 


It should be noted again that the presentation space is not a client window presentation 
space; it is a presentation space for the frame window returned by WinBeginPaint, that 
is, a cached presentation space in frame (not client) window coordinates, clipped to the 
area of the frame that needs to be updated (possibly including areas outside the client 

window). 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


WM_FLASHWINDOW 


An application has issued a WinFlashWindow function. 


Parameters 
param1 


usFlash (USHORT) 
Flash indicator. 


TRUE Start the window border flashing 
FALSE Stop the window border flashing. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE ~~ Successful completion 
FALSE — Error occurred. 


Default Processing 
The frame control window procedure responds to this message from an aonication by 
starting or stopping the flashing of the window border, and by setting rc as appropriate. 
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WM_FOCUSCHANGE (in Frame Controls) 
For the cause of this message, see “WM_FOCUSCHANGE?” on page 10-47. 


For a description of the parameters, see “WM_FOCUSCHANGE” on page 10-47. 


Remarks 

The frame control responds to this message by sending the other messages depending on 
the value of the fsFocusChange parameter. These messages, if sent, are sent in the 
following order: 


. WM_SETFOCUS to the window losing the focus. 

. WM_SETSELECTION to the windows losing their selection. 
. WM_ACTIVATE to the windows being deactivated. 

. WM_ACTIVATE to the windows being activated. 

. WM_SETSELECTION to the windows being selected. 

. WM_SETFOCUS to the window receiving the focus. 


Oah@adND — 


Default Processing 
The default window procedure sends this message to either the owner, if one exists, or to 
the parent of the window, if it is not the desktop window, otherwise it sets u/Reserved to 0. 


Related Messages 
* WM_FOCUSCHANGE 


WM_FORMATFRAME (in Frame Controls) 
For the cause of this message, see “WM_FORMATFRAME?” on page 10-48. 


For a description of the parameters, see “WM_FORMATFRAME” on page 10-48. 


Remarks 
Applications that subclass frame controls may find that the frame is already subclassed; the 
number of frame controls is variable. 


_ The WM_FORMATFRAME and WM_QUERYFRAMECTLCOUNT messages must always be 
subclassed by calling the previous window procedure and modifying its result. 


Default Processing 

The SWP structure for the FID_CLIENT frame control, if present, is the last element of the 
pswp parameter, unless additional frame controls are added by subclassing; the SWP 
structures for these follow that for FID CLIENT if present. The frame control window 
procedure first sends the message to the FID CLIENT window. If FID CLIENT returns 
ccount to indicate that the message has been processed, no additional processing is 
performed. 


If not processed by the client, the frame control window procedure calculates the size and 
position of all the standard frame controls. 
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Related Messages 
e WM_FORMATFRAME 


WW_INITMENU (in Frame Controls) 
For the cause of this message, see “WM_INITMENU” on page 10-53. 


For a description of the parameters, see “WM_INITMENU” on page 10-53. 


Remarks 

The identity of the top-level action-bar menu that generated this message is found. If the 
identity is FID_ MENU, the message is passed to the window with identity FID_CLIENT. If 
the identity is FID SYSMENU the system menu state is initialized according to the current 
state of the window. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_INITMENU 


WM_MEASUREITEM (in Frame Controls) 
For the cause of this message, see “WM_MEASUREITEM” on page 10-55. 


For a description of the parameters, see “WM_MEASUREITEM” on page 10-55. 


Remarks 
The identity of the top-level action bar menu that generated this message is found. If the 
identity is FID_MENU, the message is passed to the window with identity FID CLIENT. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sHeight to the default value of 0. 


Related Messages 
¢ WM_MEASUREITEM 
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WM_MENUSELECT (in Frame Controls) . 
For the cause of this message, see “WM_MENUSELECT (in Frame Controls).” 


For a description of the parameters, see “WM_MENUSELECT (in Frame Controls).” 


Remarks 
The identity of the top-level action-bar menu that generated this message is found. If the 
identity is FID_MENU, the message is passed to the window with identity FID_CLIENT. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
TRUE. 


Related Messages 
¢ WM_MENUSELECT 


WM_NEXTMENU (in Frame Controls) 
For the cause of this message, see “WM_NEXTMENU” on page 10-63. 


For a description of the parameters, see “WM_NEXTMENU’ on page 10-63. 


Remarks 

The frame control window procedure processes the message by returning the handle of the 
system menu window if hwndMenu is the handle of the main action bar window, or by 
returning the handle of the main action bar window if hwndMenu is the handle of the system 
menu window. 


Default Processing 
The default window procedure takes no action on this message, other than to set 
hwndNewMenu to NULLHANDLE. 


Related Messages 
¢ WM_NEXTMENU 


WM_OWNERPOSCHANGE 
This message is sent by a frame window processing the WM_ADJUSTFRAMEPOS 
message. 
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Parameters 
param1 


ppswp (PSWP) 
Owned window state. 


This points to a SWP structure. 


The receiver of this message is expected to alter this SWP parameter to the 
appropriate values relative to the new position and/or size of its owner, whose new 
position and size is specified in a SWP structure in the ppswoOwner parameter. 


param2 


ppswpOwner (PSWP) 
Owner window state. 


This points to a SWP structure. 


This represents the new position and size of the owner window. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WNM_PAINT (in Frame Controls) 
For the cause of this message, see “WM_PAINT” on page 10-66. 


For a description of the parameters, see “WM_PAINT” on page 10-66. 


Default Processing 

The frame is redrawn as governed by the FCF_BORDER or FCF_DLGBORDER style. A 
WM_ERASEBACKGROUND message is sent to FID_CLIENT window, and if it returns 
FALSE, then the FID_CLIENT window is erased to the system-provided window background 
color and sets ulReserved to 0. 


Related Messages 
¢ WM_PAINT 
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WM_QUERYBORDERSIZE 


This message is sent to the frame window to determine the width and height of the border of 
the window. 


Parameters 
param1 


pSize (PWPOINT) 
Width and height of size border control. 


This points to a POINTL structure, that is used to hold the width in the x parameter 
and the height in the y parameter. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The frame window responds to this message by returning the width and height of its border 
in the pSize parameter, as follows: 


¢ SV_CX/CYSIZEBORDER if FCF_SIZEBORDER is specified 
¢ SV_CX/CYDLGFRAME if FCF_DLGBORDER is specified 
¢ SV_CX/CYBORDER if FS_BORDER is specified. 


Default Processing 


The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set re to the default value of FALSE. 


WM_QUERYCONVERTPOS (in Frame Controls) 7 
For the cause of this message, see “WM_QUERYCONVERTPOS’ on page 10-72. 


For a description of the parameters, see “WM_QUERYCONVERTPOS?’ on page 10-72. 


Remarks 
The frame control window procedure returns QCP_NOCONVERT. 
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Default Processing 
For the default window procedure processing of this message see 
WM_QUERYCONVERTPOS 


Related Messages 
¢ WM_QUERYCONVERTPOS 


WM_QUERYFOCUSCHAIN 


This message is used to request the handle of a window in the focus chain. 


Parameters 
param 


fsCmd (USHORT) 
Command to be performed. 


This field contains a flag to indicate what action is to be performed: 


QFC_NEXTINCHAIN Return the next window in the focus chain. 
The hwndParent parameter is not used. 


QFC_ACTIVE Return the handle of the frame window that would be 
activated or deactivated, if this window gains or loses the 
focus. 


The window handle returned is a child of the window 
specified by the hwndParent parameter. 


QFC_FRAME Return the handle of the first frame window associated 
with this window. 


The hwndParent parameter is not used. 


QFC_SELECTACTIVE Return the handle of the window from the group of owned 
windows to which this window belongs which either 
currently has the focus or, if no window has the focus, 
previously had the focus. 


Return NULL, if no window in the owner group has had 
the focus. 


The hwndParent parameter is not used. 


QFC_PARTOFCHAIN _ Return TRUE if the handle of the window identified by the 
hwndParent parameter is in the focus chain, otherwise 
return FALSE. 


Because this message is passed along the focus chain, 
this is equivalent to returning TRUE, if the handle of the 
window receiving this message is hwndParent or to 
returning FALSE, if it is not. 
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param2 


hwndParent (HWND) 
Parent window. 


Returns 
hwndResult (HWND) 
Handle of the window requested. 


0 No window handle exists for this case of the fsCmd parameter 


This value js also to be interpreted as FALSE for the case when the fsCmd is 
set to QFC_PARTOFCHAIN. 


Other Handle of the window requested. 


This value is also to be interpreted as TRUE for the cases when the fsCmd is 
set to QFC_PARTOFCHAIN. 


Remarks 
The frame control window procedure responds to this message by returning the appropriate 
window handle, as described under the fsCmd field. 


Default Processing 
The default window procedure takes the same action as the frame control window saeaaure: 


WM_QUERYFRAMECTLCOUNT 


This message is sent to the frame window in response to the receipt of a WM_SIZE ora 
WM_UPDATEFRAME (in Frame Controls) message. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sControlCount (SHORT) 
Count of frame controls. 
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Remarks 

By sending this message to itself, any procedures that subclass the frame window become 
aware that the number of frame controls is being calculated and include any special frame 
controls of the subclass in the count. 


This count is used to allocate the appropriate number of SWP structures that are passed in 
the WM_FORMATFRAME (in Frame Controls) message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sContro/Count to the default value of 0. . 


WM_QUERYFRAMEINFO 


This message enables an application to query information about frame windows. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
flFlags (ULONG) 
Frame information flags. 


Fl_FRAME Identifies a frame window. 

FlOWNERHIDE The frame window is hidden when its owner is hidden. 
FI_NOMOVEWITHOWNER __ The frame window does not move with its owner. 
Fl_ACTIVATEOK The frame window may be activated. This means, for 


example, that the frame window is not disabled. 


Remarks 
This message can be used to query whether or not a particular window is a frame window. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 


to 0. 
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WM_QUERYICON 


This message is sent to a frame window to query its associated icon. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
hptricon (HPOINTER) 
Handle to the icon. 


Default Processing 
The icon for the frame is returned. 


WM_QUERYWINDOWPARAMS (in Frame Controls) 


This message occurs when an application queries the frame control window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Default Processing 

The frame control window procedure queries the appropriate window parameters in 
accordance with pwndparams and sets rc to TRUE if the operation is successful, otherwise 
to FALSE. 


The window text of a frame control is obtained by sending this message to its 
FID_TITLEBAR. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 
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WM_SETBORDERSIZE 


This message is sent to the frame window to change the width and height of the border. 


Parameters 
param 


uscx (USHORT) 
Width of border. 


param2 


uscy (USHORT) 
Height of border. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The frame control sets the width and height to uscx and uscy respectively. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


WM_SETICON 


This message is sent to a frame window to set its associated icon. 


Parameters 
param1 


hptricon (HPOINTER) 
New icon handle. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Default Processing 
The icon for the frame is set. 


WM_SETWINDOWPARAMS (in Frame Controls) 
This message occurs when an application sets or changes the frame control window 
parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS?” on page 10-86. 


Default Processing 
The frame control window procedure sets the appropriate window parameters in accordance 
with pwndparams and sets rc to TRUE if the operation is successful, otherwise to FALSE. 


The window text of a frame control is set by sending this message to its FID_TITLEBAR. 


Related Messages 
¢ WM_SETWINDOWPARAMS 


WWM_SIZE (in Frame Controls) 
For the cause of this message, see “WM_SIZE” on page 10-88. 


For a description of the parameters, see “WM_SIZE” on page 10-88. 


Default Processing 
The frame control window procedure responds to this message by sending a 
WM_FORMATFRAME (in Frame Controls) message to itself and by setting u/Reserved to 0. 


Related Messages 
° WM_SIZE 
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WM_SYSCOMMAND 


This message occurs when a control window has a significant event to notify to its owner, or 
when a key stroke has been translated by an accelerator table into a WM_SYSCOMMAND. 


Parameters 
param1 


uscmd (USHORT) 
Command value. 


The frame control takes the action described on these uscmd values: 


SC_SIZE 
SC_MOVE 


SC_MINIMIZE 


SC_MAXIMIZE 


SC_RESTORE 
SC_NEXT 

SC_APPMENU 
SC_SYSMENU 


SC_CLOSE 


SC_NEXTFRAME 


SC_NEXTWINDOW 


Sends a WM_TRACKFRAME (in Frame Controls) to the 
frame window. 


Sends a WM_TRACKFRAME (in Frame Controls) to the 
frame window. 


If a control with the identifier FID _MINMAX is present, 
minimizes the frame window, or restores it to a 
remembered size and position. 


If a control with the identifier FID_MINMAX is present, 
maximizes the frame window, or restores it to a 


remembered size and position. 


When a window is moved or sized in the normal way at 
least one border should remain on the screen. Whena 
window is maximized and the maximum size is as large as 
the screen, all borders should be positioned just outside 
the screen. 


If a contro! with the identifier FID _MINMAX is present, 
restores a maximized frame window to its previous size 
and position. 


Cycles the active window status to the next main window. 


Sends a MM_STARTMENUMODE message to the control 
with the identifier FID_ MENU. 


Sends a MM_STARTMENUMODE message to the control 
with the identifier FID_SYSMENU. 


If Close is not enabled in the system menu, this message 
is ignored. Otherwise the frame posts a WM_CLOSE 
message to the client if it exists or to itself, if not. 


The next frame window that is a child of the desktop 
window is activated. 


The next window with the same owner window is 
activated. 
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SC_TASKMANAGER 
SC_HELPEXTENDED 


SC_HELPKEYS 


SC_HELPINDEX 


SC_HIDE 


param2 


ussource (USHORT) 
Source type. 


The Task List is activated. 


The frame manager sends HM_EXT_HELP to the 
associated Help Manager Object Window. If there is no 
such associated window, the original message is sent to 
the client. 


The frame manager sends HM_KEYS_HELP to the 
associated Help Manager Object Window. If there is no 
such associated window, the original message is sent to 
the client. 


The frame manager sends HM_HELP_INDEX to the 
associated Help Manager Object Window. If there is no 
such associated window, the original message is sent to 
the client. 


Sets the visibility state of the frame window to off causing 
it to appear hidden or invisible. 


Identifies the type of control: 


CMDSRC_PUSHBUTTON Posted by a push-button control: uscmd is the 


CMDSRC_MENU 


window identifier of the push button. 


Posted by a menu control: uscmd is the identifier of 
the menu item. 


CMDSRC_ACCELERATOR Posted as the result of an accelerator: uscmd is the 


CMDSRC_OTHER 


fpointer (BOOL) 


Pointing-device indicator. 


accelerator command value. 


Other source: uscmd gives further control-specific 
information defined for each control type. 


TRUE ~The message is posted as a result of a pointing-device operation. 
FALSE The message is posted as a result of a keyboard operation. 


ulReserved (ULONG) 


Reserved value, should be 0. 


Remarks 
This message is posted to the window procedure of the owner of the frame control. 
ulReserved is set to 0. : 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


WM_TRACKFRAME (in Frame Controls) 


This message is sent to a frame window whenever it is to be moved or sized. 


Parameters 
param1 


fsTrackFlags (USHORT) 
Tracking flags. 


Contains a combination of one or more TF_* flags; for details, see the TRACKINFO 
data structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE — Successful completion 
FALSE _ Error occurred, or the operation is terminated. 


Remarks 

The frame control window procedure responds to this message by causing a tracking 
rectangle to be drawn to move or size the window. For information, see the WinTrackRect 
function. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
TRUE. 


Related Messages 
¢ WM_TRACKFRAME 
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WM_TRANSLATEACCEL (in Frame Controls) 


For the cause of this message, see “WM_TRANSLATEACCEL” on page 10-95. 


For a description of the parameters, see “WM_TRANSLATEACCEL’ on page 10-95. 


Remarks 
The frame control window procedure processes the message by checking whether the 
character is in the accelerator table, by using the WinTranslateAccel function. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_TRANSLATEACCEL 


WM_TRANSLATEMNEMONIC (in Frame Controls) 


For the cause of this message, see “WM_TRANSLATEMNEMONIC” on page 10-96. 


For a description of the parameters, see “WM_TRANSLATEMNEMONIC’ on page 10-96. 


Remarks 
The frame control window procedure processes the message by sending it to the application 
menu window, that is, the window with the identity FID_- MENU. 


Default Processing 
For the default window procedure processing of this message, see 
“WM_TRANSLATEMNEMONIC’ on page 10-96. 


Related Messages 
¢ WM_TRANSLATEMNEMONIC 


WM_UPDATEFRAME (in Frame Controls) 


For the cause of this message, see “WM_UPDATEFRAME?” on page 10-97. 


For a description of the parameters, see “WM_UPDATEFRAME?” on page 10-97. 


Remarks 

This message must be sent to the frame window whenever an application adds or removes 
one of the frame controls identified by the FCF_* flags. It must also be sent if the 
application adds or removes a submenu of the menu bar of the frame window. 


The frame control window procedure first sends the message on to the FID_CLIENT window. 
The FID_CLIENT window might either reformat the frame window and set rc to TRUE, in 
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which case the frame control window procedure takes no further action, or it might set rc to 
FALSE, in which case the frame control window procedure performs the reformatting. 


If fiCreateFlags contains FCF_SIZEBORDER, reformatting the frame window includes 
invalidating the area occupied by the size border. 


The frame control window procedure sets rc to TRUE. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
TRUE. 


Related Messages 
¢ WM_UPDATEFRAME 
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Chapter 14. List Box Control Window Processing 


This system-provided window procedure processes the actions on a list box control 
(WC_LISTBOX). 


Purpose 
A list box control is a window containing a list of items. Each item in a list box contains a 
text string (0 or more characters) and a handle. The text string is displayed in the list box 
window. The handle can be used by the application to refer to other data associated with 
each item. 


List Box Control Styles 
These list box control styles are available: 


LS_HORZSCROLL _ The list box control enables the operator to scroll the list box 
horizontally. 


LS _MULTIPLESEL _ The list box control enables the operator to select more than one 
item at any one time. Lists that do not have this style allow only a 
single selection at any one time. If this style is specified, 

*LS_EXTENDEDSEL should also be specified. 


LS_EXTENDEDSEL if this style is specified, the extended selection user interface is 
enabled. 


LS_OWNERDRAW _ The list box control has one or more items that can be drawn by the 
owner. Typically, these items are represented by bit maps rather 
than by text strings. 


LS_NOADJUSTPOS _ If this style is included, the list box control is drawn at the size 
specified. This can cause parts of an item to be shown. 


List Box Control Data 
None. 


Default Colors 
The following system colors are used when the system draws button controls: 


SYSCLR_FIELDBACKRGOUND 
SYSCLR_BUTTONDARK 
SYSCLR_WINDOW 
SYSCLR_WINDOWTEXT 
SYSCLR_ENTRYFIELD 
SYSCLR_HILITEFOREGROUND 
SYSCLR_HILITEBACKGROUND 
SYSCLR_WINDOWFRAME 
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Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_DISABLEDFOREGROUNDCOLOR 
PP_FOREGROUNDCOLOR | 
PP_HILITEFOREGROUNDCOLOR 
PP_BORDERCOLOR 
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List Box Control Notification Messages 


These messages are initiated by the list box control window to notify its owner of significant 
events. 


WM_CONTROL (in List Boxes) 
For the cause of this message, see “WM_CONTROL” on page 10-39. 


Parameters 
param1 


id (USHORT) 
Control-window identity. 


usnotifycode (USHORT) 
Notify code. 


The list box control window procedure uses these notification codes: 


LN_ENTER Either the Enter or Return key has been pressed while the list 
box control has the focus, or the list box control has been 
double-clicked. 


LN_KILLFOCUS _ The list box control loses the focus. 


LN SCROLL The list box control is about to scroll horizontally. This can 
happen when the application has issued a WinScrollWindow 
function. 

LN_SETFOCUS _ The list box control receives the focus. 

LN_SELECT An item is being selected (or deselected). 


Note: To discover the index of the selected item, the 
application must use the LM_QUERYSELECTION 
message. 


param2 


hwndcontrolspec (HWND) 
List box control window handle. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 
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Remarks | 
The list box control window procedure generates this message and sends it to its owner, 
informing the owner of this event. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


Related Messages 
¢ WM_CONTROL 


WM_DRAWITEM (in List Boxes) 


This notification is sent to the owner of a list box control each time an item is to be drawn. 


Parameters 
param1 


idListBox (USHORT) 
Window identifier. 


The window identity of the list box control sending this notification message. 


param2 


pOwnerltem (POWNERITEM) 
Owner-item structure. 


This points to an owner-item structure; see “OWNERITEM” on page A-136. 


Returns 
re (BOOL) 
ltem-drawn indicator. 


TRUE The owner draws the item, so the list box control does not draw it. 
FALSE _ If the item contains text and the owner does not draw the item, the owner 
returns this value, and the list box contro! draws the item. 


Remarks 
The list box control window procedure only draws items that are represented by text strings 
and emphasizes selected items by inverting them. 


If an application uses list box controls containing items that are not represented by text 
strings, or requires that the emphasized state of an item is to be drawn in a special manner, 
the list box control must specify the style LS OWNERDRAW and those items must be drawn 
by the owner. 
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The list box control window procedure generates this message and sends it to the owner of 
the list box control, informing the owner that an item is to be drawn, offering the owner the 
opportunity to draw that item, and indicating that either the item has been drawn, or that the 
list box control is to draw it. 


The item text must not be changed during the processing of this message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


Related Messages 
¢ WM_DRAWITEM 


WM_MEASUREITEM (in List Boxes) 


This notification is sent to the owner of a list box control to establish the height and width for 
an item in that control. 


Parameters 
param1 


sListBox (SHORT) 
List-box identifier. 


param2 


sitemindex (SHORT) 
Item index. 


The zero-based index of the item which has changed. 


Returns 
ReturnCode 


sHeight (SHORT) 
Height of item. 


sWidth (SHORT) 
Width of item. 


This value is required only if the list box control is scrollable horizontally, that is, it 
has a style of LS_HORZSCROLL. 


Remarks 
This message is sent to the owner of a list box that has a style of LS_OWNERDRAW, to 
offer the owner an opportunity to establish the height and width (for a horizontally scrollable 
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list box control) of an item that accommodates any special requirements for the drawing of 
items in that list box. It is sent when items in the list box are inserted or deleted, and also 
when presentation parameters for the list box change. 


All items in a list box must have the same height, which must be greater than or equal to the 
height of the current font. 


In particular, this notification is sent to the owner of a list box that has a style of 
LS_OWNERDRAW, to offer the owner an opportunity to establish the height and width (for a 


‘horizontally scrollable list box control) of an item that accommodates any special 
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requirements for the drawing of items in that list box. 

Default Processing 

The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sHeight to the default value of 0. 


Related Messages 
¢ WM_MEASUREITEM 
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List Box Control Window Messages 


This section describes the list box control window procedure actions on receiving the 
following messages. 


LM DELETEALL 


This message is sent to a listbox control to delete all the items in the list box. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The list box control window procedure responds to this message by deleting all the items in 
the list box and by setting rc to TRUE. 


Default Processing 
The default window procedure does not expect to receive this message and, therefore, takes 
no action on it, other than to set rc to the default value of FALSE. 


LM_DELETEITEM 


This message deletes an item from the list box control. 


Parameters 
paramt 


sltemindex (SHORT) 
item index. . 


The zero-based index of the item to be deleted. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sltemsLeft (SHORT) 
Number remaining. 


The number of items in the list after the item is deleted. 


Remarks 

The list box control window procedure responds to this message by deleting the indexed item 
of the list box and by setting s/temsLeft to the count of the items in the list after the item is 
deleted. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set s/temsLeft to the default value of 0. 


LM_INSERTITEM 


This message inserts an item into a list box control. 


Parameters 
param1 


sltemIndex (SHORT) 
Item index. 


LIT_END Add the item to the end of the list. 

LIT SORTASCENDING Insert the item into the list sorted in ascending order. 

LIT SORTDESCENDING __ Insert the item into the list sorted in descending order. 

Other Insert the item into the list at the offset specified by this 
zero-based index. 


param2 
pszitemText (PSZ) 


Item text. 


This points to a string containing the item text. 
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Returns 
sindexinserted (SHORT) 
index of inserted item. 


LIT. MEMERROR _ The list box control cannot allocate space to insert the list item in 


the list. 
LIT_ ERROR An error, other than LIT_MEMERROR, occurred. 
Other The zero-based index of the offset of the item within the list. 


Remarks 

The list box control window procedure responds to this message by inserting the item text 
identified by the pszitemText parameter into the position in the list specified by the 
sltemindex parameter. 


The sorting sequence used is that defined by the WinCompareStrings function. 


The list box control sets s/ndex/nserted to the zero-based index of the offset of the item 
within the list. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set s/ndex/nserted to the default value of 0. 


LM_INSERTMULTITEMS 


This message inserts one or more items into a list box. 


Parameters 
param1 


pListboxinfo (PLBOXINFO) 
Pointer to a structure containing list box information. 


param2 


papszText (PSZ *) 
Pointer to an array of pointers to text strings. 
This parameter is a pointer to an array of pointers to zero-terminated strings. The 


array must contain at least ulltemCount items. (ulltemCount is a field in 
LBOXINFO.) 


lf this parameter is set to NULL, a ulltemCount number of empty items are inserted 
into the list. This is useful for ownerdraw listboxes that do not make use of text 
strings. 
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Returns 
iCount (LONG) 
Number of items successfully inserted into the list. - 


If the number of items is not the same as ulltemCount, an error has occured. 


Remarks | 
LM_INSERTMULTITEMS inserts multiple items into a list box at one time, up to 32 768 
items. | 


If either LIT_SORTASCENDING or LIT_SORTDESCENDING is specified in the //temindex 
field of LBOXINFO, then the complete list is sorted after the items have been inserted. If 
items are being added using several LM_INSERTMULTITEMS messages, it is faster to 
specify LIT_END for all the insert messages except the last one, and then set one of the sort 
flags to sort the entire list after the last set of items have been inserted. 


The sorting sequence is the same as that defined for WinCompareStrings. 


WM_MEASUREITEM (in List Boxes) is sent to the owner of an ownerdraw list box for every 
item inserted into the list box. 


Default Processing 
The default message procedure sets /Count to zero. 


LM_QUERYITEMCOUNT 


This message returns a count of the number of items in the list box control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
siltemCount (SHORT) 
Item count. 


Remarks 
The list box control window procedure responds to this message by setting s/temCount to the 
number of items in the list. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set s/temCount to the default value of 0. 


LM QUERYITEMHANDLE 


This message returns the handle of the indexed item of the list box control. 


Parameters 
param1 


sltemiIndex (SHORT) 
Item index. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulltem (ULONG) 
Item handle. 


0 The indexed item does not exist. 
Other Item handle. 


Remarks 
The meaning of the item handle is defined by the application. It may, for example, be a 
pointer to an application defined data structure. 


Item handles are initialized to NULLHANDLE when an item is created. The list box control 
window procedure responds to this message by setting u/ltem to the handle of the item 
whose index is specified by s/tem/ndex. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set u/ltem to the default value of NULLHANDLE. 


The item handle is initialized to NULLHANDLE. 
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LM_QUERYITEMTEXT 


This message returns the text of the specified list box item. 


Parameters 
param1 


sltemindex (SHORT) 
Item index. 


smaxcount (SHORT) 
Maximum count. 


0 No text is copied. 
Other Copy the item text as a null-terminated string, but limit the number of 
characters copied, including the null termination character, to this value. 


param2 


pszitemText (PSZ) 
Buffer into which the item text is to be copied. 


This points to a string (character) buffer. 


Returns 
sTextLength (SHORT) 
Length of item text. 


The length of the text string, excluding the null termination character. 


Remarks 

The list box control window procedure responds to this message by copying up to smaxcount 
characters, as a null-terminated string, from the text of the item specified by s/tem/ndex into 
the buffer identified by pszitemText. 


The length of the item text can be determined by using the LM_QUERYITEMTEXTLENGTH 
message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sTextLength to the default value of 0. 
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LM_QUERYITEMTEXTLENGTH 


This message returns the length of the text of the specified list box item. 


Parameters 
param1 


sltemindex (SHORT) 
. Item index. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sTextLength (SHORT) 
Length of item text. 


The length of the text string, excluding the null termination character. 


LIT ERROR Error occurred. For example, the item specified by its index does not 
exist. 


Other Length of item text. 


Remarks 
The list box control window procedure responds to this message by setting sTextLength to 
the length in characters of the text of the item specified by s/tem/ndex. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than set sTextLength to the default value of 0. 


LM_QUERYSELECTION 


This message is used to enumerate the selected item, or items, in a list box. 


Parameters 
param1 


sltemStart (SHORT) 
Index of the start item. 


If the list box allows multiple selected items, that is, if it has a style of 
LS_MULTIPLESEL, then this parameter indicates the index of the item from which 
the search for the next selected item is to begin. Therefore, to get all the selected 
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items of the list, this message is sent repeatedly, each time setting this parameter to 
the index of the item returned by the previous usage of this message. 


If this parameter is set to LIT CURSOR the index of the item in the list box which 
currently has the cursor is returned. 


If the list box only allows a single selection, this parameter is ignored. 


LIT CURSOR Return the index of the item in the list box which currently has the 


cursor. 
LIT_FIRST Start the search at the first item. 
Other Start the search after the item specified by this index. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sitemSelected (SHORT) 
Index of the selected item. 


LIT_NONE _ No selected item. 


For a single selection list box, this implies that there is no selected item in 
the list box. For a multiple selection list box, this implies that there is no 
selected item in the list box whose index is higher than the index specified 
by the s/temSitart parameter. 


Other Index of selected item. For a single selection list box, this is the index of 
the only selected item in the list box. For a multiple selection list box, this 
is the index of the next selected item in the list box whose index is higher 
than the index specified by the s/temStart parameter. 


lf sltemStart is set to LIT_CURSOR, the index of the list-box item which 
currently has the cursor is returned. 


Remarks 

The list box control window stocedurs responds to this message by returning in 
sitemSelected the zero-based index of the selected item or next selected item after — 
sitemStart, if any. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
-no action on it, other than set s/temSelected to the default value of 0. 
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LM_QUERYTOPINDEX 


_ This message obtains the index of the item currently at the top of the list box. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sitemTop (SHORT) 
Index of the item currently at the top of the list box: 


LIT NONE _ No items in the list box 
Other Index of the item currently at the top of the list box. 


Remarks 
The list box control window procedure responds to this message by returning in sitemTop the 
zero-based index of the item currently at the top of the list box. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sitemTop to the default value of 0. 


LM_SEARCHSTRING 


This message returns the index of the list box item whose text matches the string. 


Parameters 
param1 


uscmd (USHORT) 
Command. 


Defines the criteria by which the string specified by the pszSearchString parameter 
is to be compared with the text of the items, to determine the index of the first 
matching item. 


These values can be combined using the logical-OR operator: 
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LSS_CASESENSITIVE Matching occurs if the item contains the characters 
specified by the pszSearchString parameter exactly. 


This value is mandatory. 


LSS PREFIX Matching occurs if the leading characters of the item 
contain the characters specified by the pszSearchString 
parameter. 


If this value is specified, LSS SUBSTRING must not be 
specified. 

LSS_SUBSTRING Matching occurs if the item contains a substring of the 
characters specified by the pszSearchString parameter. 


lf this value is specified, LSS_PREFIX must not be 
specified. 


sitemStart (SHORT) 
Index of the start item. 


LIT_FIRST Start the search at the first item. 
Other Start the search after the item specified by this index. 


param2 


pszSearchString (PSZ) 
Search string. 


This points to the string to search for. 


Returns 
sltemMatched (SHORT) 
Index item whose text matches the string. 


LIT ERROR _ Error occurred 
LIT_NONE No item found 
Other Index item whose text matches the string. 


Remarks | 
The list box control window procedure responds to this message by setting sitemMatched to 
the index of the next item whose text matches the string specified by pszSearchString. 


All the items of the list are searched until a match is found, that is, the search wraps from the 
end to the start of the list. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sitemMatched to the default value of 0. 
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LM_SELECTITEM 


This message is used to set the selection state of an item in a list box. 


Parameters 
param1 


sltemindex (SHORT) 
Index of the item to be selected or deselected: 


LIT NONE All items are to be deselected 
Other Index of the item to be selected or deselected. 


param2 


usselect (USHORT) 
Select flag. 


(Ignored if sitemindex is set to LIT_NONE). 


TRUE _ The item is selected. If the control is a single selection list box (that is, it 
does not have the style of LS_MULTIPLESEL), any previously selected 
item is deselected. 


FALSE _ The item is deselected. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE Error occurred. For example, when the item does not exist in the list box, or 
when an item that is not selected is deselected. 


Remarks 
The list box control window procedure responds to this message by setting the selection 
state, as indicated by usselect, of the item whose index is specified in s/temindex. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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LM_SETITEMHANDLE 


This message sets the handle of the specified list box item. 


Parameters 
param1 


sitemindex (SHORT) 
Item index. 


param2 


ulltemHandle (ULONG) 
Item handle. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
‘FALSE — Error occurred. 


Remarks 
The meaning of the item handle is defined by the application. It may, for example, be a 
pointer to an application defined data structure. 


Item handles are initialized to NULLHANDLE when an item is created. 


The list box control window procedure responds to this message by setting the handle of the 
item whose index is specified by s/tem/ndex to the value specified by u/ltemHandle. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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LM_SETITEMHEIGHT 


This message sets the height of the items in a list box. 


Parameters 
param1 


flNewHeight (ULONG) 
Height of items in list box. 


param2 


ulReserved (ULONG) 


Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful operation 
FALSE — Error occurred. 


Remarks 


The list box control window procedure responds to this message by setting the height of the 
items in a list box to that specified by flNewHeight. 


This message does not send a WM_MEASUREITEM message. 


Default Processing 


The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


LM_SETITEMTEXT 


This message sets the text into the specified list box item. 


Parameters 
param1 


sitemindex (SHORT) 
Item index. 
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param2 


pszitemText (PSZ) 
Item text. 


This points to a string containing the text to set the list-box item to. 


Returns 
re (BOOL) 
Success indicator. 


TRUE = Successful completion 
FALSE _ Error occurred. 


Remarks 

The list box control window procedure responds to this message by copying the text 
identified by the pszitemText parameter into the item in the list specified by the s/temindex 
parameter. 


Default Processing , 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


LM_SETITEMWIDTH 


This message sets the width of the items in a list box. 


Parameters 
param1 


INewWidth (ULONG) 
Width of items in list box. 


param2 


reserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 
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Remarks 
The list box control window procedure responds to this message by setting the width of the 
items in a list box to that specified by INewWiath. 


Note: Only list boxes with the LS HORZSCROLL style set will respond to this message. 
This message does not send a WM_MEASUREITEM message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


LM_SETTOPINDEX 


This message is used to scroll a particular item to the top of the list box. 


Parameters 
param1 


sltemindex (SHORT) 
index of the item to be made top. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE — Successful completion 
FALSE = Error occurred. 


Remarks 
The list box control window procedure responds to this message by scrolling the item whose 
index is identified by sitem/ndex to the top of the list box. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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WM_CHAR (in List Boxes) 
For the cause of this message, see “WM_CHAR’” on page 10-32. 


For a description of the parameters, see “WM CHAR” on page 10-32. 


Remarks 7 

The list box control window procedure responds to this message by sending it to its owner if — 
it has not processed the key stroke. This is the most common means by which the input 
focus is switched around the various controls in a dialog box. 


The key strokes processed by a list box control are: 


Down Arrow Moves the selection down one item, scrolling the list box by one item, if 
necessary, to make the next item visible. When the selection reaches the 
bottom, the Down Arrow has no effect. 


Up Arrow Moves the selection up one item, scrolling the list box by one item, if 
necessary, to make the previous item visible. When the selection reaches 
the top, the Up Arrow has no effect 


Page Down Moves the selection down one page, scrolling the list box by the number of 
items visible in the list box. 


For example, if the list box displays seven items and item 1 is selected and 
positioned at the top of the list box, pressing the Page Down key causes 
item 8 to be selected and displayed at the top of the list box. Pressing 
Page Down when the last item is selected has no effect. 


Page Up Moves the selection up one page, scrolling the list box by the number of 
items visible in the list box. 


For example, if the list box displays seven items and item 8 is selected and 
positioned at the top of the list box, pressing the Page Up key causes item 
1 to be selected and displayed at the top of the list box. Pressing the 
Page Up key when the first item is selected has no effect. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE 


Related Messages 
¢ WM_CHAR 
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WM_QUERYCONVERTPOS (in List Boxes) 
For the cause of this message, see “WM_QUERYCONVERTPOS?’ on page 10-72. 


For a description of the parameters, see “WM_QUERYCONVERTPOS?” on page 10-72. 


Remarks 
The list box contro! window procedure returns QCP_NOCONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS” on page 10-72. 


Related Messages 
¢ WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in List Boxes) 


Occurs when an application queries the list box control window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Remarks 


The list box control window procedure responds to this message by passing it to the default 


window procedure. 


Default Processing 


The default window procedure sets the cchText, cbPresParams, and cbCtiData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to 0 and sets rc to FALSE. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 


WM_SETWINDOWPARAMS (in List Boxes) 


This message occurs when an application sets or changes the list box control window 
parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS?” on page 10-86. 


Remarks 


The list box control window procedure responds to this message by passing it to the default 


window procedure. 


Default Processing 


The default window procedure takes no action on this message, other than to set result to 


FALSE. 
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Related Messages 
¢ WM_SETWINDOWPARAMS 
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Chapter 15. Menu Control Window Processing 


This system-provided window procedure processes the actions on a menu control 
(WC_MENU). 


Purpose 
A menu conirol is a child or pull-down window that contains a list of selection items. These 
items can be represented by text strings, separators, bit maps or menu buttons. Menu 
templates can be loaded as resources and the menu can be created automatically when the 
parent window is created. The application can build the menu dynamically by sending 
MM_INSERTITEM messages. An application can change a menu by sending messages to 
it. 


Menus enable the operator to select one of the items in the list, using the pointing device or 
the keyboard. When a selection is made, the menu parent is notified by posting a 
WM_COMMAND, WM_SYSCOMMAND, or WM_HELP message and a unique identifier 
representing the operator’s selection. 


Menus automatically resize themselves when items are added and removed. Menus are 
automatically destroyed when their owner is destroyed. 


Typically, an application has an action bar menu and several submenus. The action bar is 
normally visible, and is a child window in the parent window frame. The submenus are 
normally hidden and become visible when selections are made on the action bar. 


Menu Control Styles 
These menu control styles are available: 


MS_ACTIONBAR The items in the list are displayed side-by-side. This 
style is used to implement a top level menu. Menus that 
do not have this style are displayed in one or more 
columns and are submenus associated with an action 
bar. 


Ail menu controls have styles CS_SYNCPAINT and 
CS_PARENTCLIP. 


MS_CONDITIONALCASCADE This style is used to specify that the items in this list are 
a conditional cascade menu. Conditional cascade menus 
act like normal cascade menus with the exception that 
the cascade does not automatically open when the user 
selects it. To open the conditional cascade menu, the 
mini-pushbutton on the menu item must be selected. If 
the menu is selected without opening the cascade, the 
default item in the cascade is selected. The default 
action on the cascade is identified by a check mark. 
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MS_TITLEBUTTON 


MS_VERTICALFLIP 


Menu Item Styles 


Used to identify menus that can be used as buttons in 
the title bar. Can only be used with MS_ACTIONBAR. 


This style causes the menu to be drawn using the CUA 
colors specified for the title bar rather than the action bar. 


Normally, pull-down menus (the default, without the 
MS_VERTICALFLIP style) are displayed below their 
associated action bar item. If there is not room on the 
screen to display the entire pull-down in this manner, and 
if there is room to display the pull-down above the action 
bar, it is displayed above the action bar. Pull-down 
menus with the MS_VERTICALFLIP style are flipped | 
vertically. That is, they are displayed above the menu if 
possible, otherwise below it. The vertical flip style must 
be set explicitly by the application when the window is 
minimized, and must be reset when it is restored. 


If an application action bar contains this style, the style is 
applied to all pull-down menus belonging to the action 
bar (the style does not directly affect the display of the 
action bar). This provides a convenient means for the 
application to flip the appearance of all pull-down menus. 


These menu item styles are available: 


MIS_SUBMENU 


MIS_SEPARATOR 


MIS_BITMAP 
MIS_TEXT 


The item is a submenu. When the user selects this type of 
item, a submenu is displayed from which the user must make 
further selection. Items that are not submenu items are 
command items. 


The display object is a horizontal dividing line. This type of 
item can only be used in pull-down menus. This type of item 
cannot be enabled, checked, disabled, highlighted, or selected 
by the user. The functional object is NULL when this style is 
specified. 


The display object is a bit map. 
The display object is a text string. 


MIS_BUTTONSEPARATOR The item is a menu button. Any menu can have zero, one, or 


MIS_BREAK 


two items of this type. These are the last items in a menu and 
are automatically displayed after a separator bar. The user 
cannot move the cursor to these items, but can select them 
with the pointing device or with the appropriate key. 


The item begins a new row or column. 
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MIS_BREAKSEPARATOR 
MIS_SYSCOMMAND 
MIS_OWNERDRAW 


MIS_HELP 


MIS_STATIC 


Menu Item Attributes 


Same as MIS_ BREAK, except that it draws a separator 
between rows or columns of a pull-down menu. This style can 
only be used within a submenu. 


If this item is selected, the menu notifies the owner by posting 
a WM_SYSCOMMAND message rather than a 
WM_COMMAND message. 


Items with this style are drawn by the owner. WM_DRAWITEM 
and WM_MEASUREITEM notification messages are sent to the 
owner to draw the item or determine its size. 


If the item is selected, the menu notifies the owner by posting a 
WM_HELP message rather than a WM_COMMAND message. 


This type of item exists for information purposes only. It cannot 
be selected with the pointing device or keyboard. 


Applications can get and set the state of these attributes by sending MM_QUERYITEMATTR 
and MM_SETITEMATTR messages. 


These menu item attributes are available: 


MIA_HILITED 


MIA_CHECKED 
MIA_DISABLED 


MIA_FRAMED 
MIA_NODISMISS 


Default Colors 


The state of this attribute is TRUE, if and only if, the item is 
selected. 


if this attribute is TRUE a check mark appears next to the item. 


This attribute is TRUE if the item is disabled and cannot be 
selected. The item is drawn in a disabled state. 


If this attribute is TRUE a frame is drawn around the item. 


If this item is selected, the pull-down menu containing this item 
should not be hidden before notifying the application window of 
the selection. A menu with this attribute is not hidden until 
such time as the application or user explicitly does so, for 
example by selecting either another menu on the action bar or 
by pressing the escape key. 


The following system colors are used when the system draws button controls: 


SYSCLR_WINDOWFRAME 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONLIGHT 


SYSCLR_SHADOW 


SYSCLR_TITLEBOTTOM 
SYSCLR_DIALOGBACKGROUND 
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Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_FOREGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLOR 
PP_BORDERCOLOR 
PP_DISABLEDFOREGROUNDCOLOR 
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Menu Control Notification Messages 


These messages are initiated by the menu control window procedure to notify its owner of 
significant events. 


WM_COMMAND (in Menu Controls) 
For the cause of this message, see “WM_ COMMAND?’ on page 10-37. 


For a description of the parameters, see “WWM_COMMAND?” on page 10-37. 


The menu control window procedure sets uscmd to the menu-item identity. 


Remarks 

The menu control window procedure generates this message if the WM_MENUSELECT (in 
Menu Controls) message returns a rc of TRUE. when an item is selected that does not have 
the style of MIS_SYSCOMMAND or MIS_HELP. The menu control window procedure posts 
the message to the queue of the window owner. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
e WM_COMMAND 


WM_DRAWITEM (in Menu Controls) 


This notification is sent to the owner of a menu control each time an item is to be drawn. 


Parameters ‘ 
param1 


idMenu (USHORT) 
Window identifier. 


The window identity of the menu control sending this notification message. 
param2 
pOwnerltem (POWNERITEM) 


Owner-item structure. 
This points to an owner-item structure; see “OWNERITEM” on page A-136. 
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Returns 
rc (BOOL) . 
Item-drawn indicator. 


TRUE The owner draws the item, and so the menu control does not draw it. 
FALSE _ If the item contains text and the owner does not draw the item, the owner 
returns this value and the menu control draws the item. 


Remarks 
The menu control window procedure only draws items that are represented by text strings 
and emphasizes selected items by inverting them. 


If an application uses menu controls containing items that are not represented by text strings, 
or requires that the emphasized state of an item is to be drawn in a special manner, then the 
menu control must specify the style MIS_OWNERDRAW and those items must be drawn by 
the owner. 


The menu control window procedure generates this message and sends it to its owner, 
informing the owner that an item is to be drawn, offering the owner the opportunity to draw 
that item, and to indicate that either the item has been drawn, or that the menu control is to 
draw it. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set re to the default value of FALSE. 


Related Messages 
¢ WM_DRAWITEM 


WM_HELP (in Menu Controls) 
For the cause of this message, see “WM_HELP” on page 10-49. 
For a description of the parameters, see “WM_HELP” on page 10-49. 


The menu control window procedure sets uscmd to the menu-item identity. 


Remarks 
- This message is identical to a WM_COMMAND message, but implies that the application 
should respond to this message by displaying help information. 


The menu control window procedure generates this message and posts it to the queue of its 
owner when an item is selected that has the style of MIS_HELP, but only if . 
WM_MENUSELECT (in Menu Controls) returns a rc of TRUE. 


Default Processing 
The default window procedure sends this message to the parent window, if it exists and is 


not the desktop. Otherwise, it sets u/Reserved to 0. 
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Related Messages 
e WM HELP 


WWN_INITMENU (in Menu Controls) 
For the cause of this message, see “WM_INITMENU” on page 10-53. 


For a description of the parameters, see “WM_INITMENU” on page 10-53. 


Remarks 
This message offers the owner the opportunity to perform some initialization on the menu 
items before they are presented. 


The menu control window procedure generates this message and sends it to its owner, 
informing the owner of the event. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
¢ WM_INITMENU 


WM_MEASUREITEM (in Menu Controls) 
This notification is sent to the owner of a menu control to establish the height for an item in 
that control. 


Parameters 
param1 


sMenu (SHORT) 
Menu identifier. 


param2_ 
pOwnerltem (POWNERITEM) 


Owner-item structure. 
This points to an OWNERITEM structure. 
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Returns 
sHeight (SHORT) 
Height of item. 


Remarks 
This message is only sent at the time the menu control is created. When the owner receives 
this message, it must calculate and return the height of an item to the control. 


All items in a menu must have the same height, and that must be greater than or equal to 
the height of the current font. 


in particular, this notification is sent to the owner of a menu that has a style of 
MIS_OWNERDRAW, to offer the owner an opportunity to establish the height of an item that 
accommodates any special requirements for the drawing of items in that menu. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sHeight to the default value of 0. 


Related Messages 
¢ WM_MEASUREITEM 


WM_MENUEND (in Menu Controls) 
For the cause of this message, see “WM_MENUEND” on page 10-56. 


For a description of the parameters, see “WM _MENUEND” on page 10-56. 


Remarks 
The menu control window procedure generates this message and sends it to its owner, 
informing the owner of this event. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulReserved 
to 0. 


Related Messages 
¢ WM_MENUEND 


WM_MENUSELECT (in Menu Controls) 
For the cause of this message, see “WM_MENUSELECT” on page 10-57. 


For a description of the parameters, see “WM_MENUSELECT” on page 10-57. 
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Remarks 
The menu control window procedure generates this message and sends it to its owner, 
informing the owner of this event. 


When the message is returned from its owner, menu control acts on rc as appropriate. 


It must not be posted to the menu control. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 


TRUE. 


Related Messages 
e WM_MENUSELECT 


WM_NEXTMENU (in Menu Controls) 
For the cause of this message, see “WM_NEXTMENU” on page 10-63. 


For a description of the parameters, see “WM_NEXTMENU” on page 10-63. 


Remarks 
The menu control generates this message and sends it to its owner, informing the owner of 
this event. 


Default Processing 
The default window procedure takes no action on this message, other than to set 
hwndNewMenu to NULLHANDLE. 


Related Messages 
e WM_NEXTMENU 
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Menu Control Window Messages 


This section describes the menu control window procedure actions on receiving the following 
messages. 


MM_DELETEITEM 


This message deletes a menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identifier. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and delete it. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


ulReserved (ULONG) | 
Reserved value, should be 0. 


Returns 
sltemsLeft (SHORT) 
Number remaining. 


The number of items in the menu after the item is deleted. 


Remarks 
The menu control window procedure responds to this message by deleting the identified item 
from the menu or its submenus. 


Note: It must be sent, not posted, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sitemsLeft to the default value of 0. 
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MM_ENDMENUMODE 


This message is sent to a menu control to terminate menu selection. 


Parameters 
param1 


usdismiss (USHORT) 
Dismiss menu indicator. 


TRUE Dismiss the submenu or subdialog window 
FALSE Do not dismiss the submenu or subdialog window. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The menu control window procedure responds to this message by terminating menu 
selection. 


Note: It must be sent, not posted, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and, therefore, takes 
no action on it, other than to set u/Reserved to the default value of 0. 


MM_INSERTITEM 


This message inserts a menu item into a menu. 


Parameters 
param1 


pmenuitem (PMENUITEM) 


Menu-item data structure. 
This points to a MENUITEM structure. 
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param2 


pszitemText (PSZ) 
Item text. 


This points to a string containing the text to be inserted. 


Returns 
sIndexinserted (SHORT) 
Index of inserted item. 


MIT_MEMERROR _ The menu control cannot allocate space to insert the menu item in 


the menu. 
MIT_ERROR An error other than MIT_MEMERROR occurred. 
Other The zero-based index of the offset of the item within the menu. 


Remarks 

The menu control window procedure responds to this message by inserting the identified 
item into the menu at the position indicated by the specified MENUITEM data structure 
(contained within the menu-item structure). If the position is MIT_END, the item is added to 
the end of the menu. If the style of the item includes MIS_TEXT, the text of the item is 
specified by pszitemText 


The menu contro! window procedure sets sindexinserted to the zero-based index of the 
position of the item within the menu. 


Note: It must be sent, not posted, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sindexinserted to the default value of 0. 


MM_ISITEMVALID 


This message returns the selectable status of a specified menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identifier. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier. 
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FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Selectable indication. 


A menu item can be selected and entered under these conditions: 


e The item is enabled and, if it is a submenu item, the item in the action bar 
associated with the submenu is enabled. If the action bar item is not enabled, the 
user cannot display the submenu. 


e¢ The item is enabled, and the submenu is displayed and being tracked with the 
pointing device or keyboard. It is unlikely, but possible, that the associated action 
bar is disabled in this instance. 


TRUE _ The user can select and enter the specified item. 
FALSE The user cannot select and enter the specified item. 


Remarks 
The menu control window procedure responds to this message by setting the return value 
depending on the selectable status of the specified item. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


MM_ITEMIDFROMPOSITION 


This message returns the identity of a menu item of a specified index. 


Parameters 
param1 


sltemIndex (SHORT) 
Item index. 
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param2. 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sidentity (SHORT) 
Item identity. 


MIT_ERROR _ Error occurred; for example, because s/temindex is not valid. 
Other Item identity. 


Remarks 
The menu control window procedure responds to this message by setting s/dentity to the 
identity of the item whose position is identified by the index specified in s/temindex. 


Note: It must be sent, not posted, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set s/dentity to the default value of 0. 


MM_ITEMPOSITIONFROMID 


This message returns the index of a menu item of a particular identity. 


Parameters 
param1 


usitem (USHORT) 
Item identifier. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
- submenus and subdialogs of the menu for an item with the specified 
identifier. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and eubdisiogs of the menu for an item with the 
specified identifier. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
sindex (SHORT) 
Item index. 


MIT_NONE Item does not exist 
Other Item index. 


Remarks 
The menu contro! window procedure responds to this message by setting sindex to the 
zero-based index of the item identified by s/ndex. 


Note: it must be sent, not posted, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sindex to the default value of MIT_NONE. 


MM_QUERYDEFAULTITEMID 


This message returns the default item id for a conditional cascade menu. For any other type 
of menu or submenu, this message returns zero. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, must be 0. 


param2 


ulReserved (ULONG) 
Reserved value, must be 0. 


Returns 
ulDefitemiD (ULONG) 
Menu id of the default menu item. 


Default Processing 
The default window procedure takes no action other than to return 0. 


Related Messages 
¢ WM_DRAWITEM (in Frame Controls) 
¢ WM_DRAWITEM (in List Boxes) 
e WM_DRAWITEM (in Menu Controls) 
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MM_QUERYITEM 


This message returns the definition of the specified menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identifier. 


usincludesubmenus (USHORT) 
Include submenus flag. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and copy its definition. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


pmenuitem (PMENUITEM) 
Menu-item data structure. 


This points to a MENUITEM structure. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
“FALSE — Error occurred. 


Remarks 
The menu control window procedure responds to this message by copying the item definition 
specified by usitem, from the menu, to the structure specified by pmenuitem. 


Note: This message does not retrieve the text for items with a style of MIS_TEXT. The 
item text is obtained by use of the MM_QUERYITEMTEXT message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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MM_QUERYITEMATTR 


This message returns the attributes of a menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identity. 


usIncludeSubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and return its state. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


usattributemask (USHORT) 
Attribute mask. 


Returns 
usState (USHORT) 
State. 


Remarks 
The menu control responds to this message by returning the state of the specified attributes 
of the identified menu item. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set usState to the default value of 0. 


Examples 

This example sends an MM_QUERYITEMATTR message to find the state of the ‘idCase’ 
menu item. It then toggles the state of the item and sends an MM_SETITEMATTR message 
to set the new state. 


Chapter 15. Menu Control Window Processing 15-17 


MM_QUERYITEMCOUNT 


This message returns the number of items in the menu. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sresult (SHORT) 
Item count. 


Remarks 
The menu control window procedure responds to this message by returning the count of the 
number of items in the menu. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sresult to the default value of 0. 


MM_QUERYITEMRECT 


This message returns the bounding rectangle of a menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identity. 
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fincludeSubmenus (BOOL) 
Include submenus indicator. 


TRUE: __ If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and return its state. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


prect (PRECTL) 
Bounding rectangle of the menu item in device coordinates relative to the menu 
window. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE — Specified item was found. 
FALSE Specified item was not found. 


Remarks 
The menu control responds to this message by returning the bounding rectangle of identified 
menu item. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of 0 (FALSE). 


MM_QUERYITEMTEXT 


This message returns the text of the specified menu item. 


Parameters 
param1 


usitem (USHORT) 
ltem identifier. 


smaxcount (SHORT) 
Maximum count. 


Copy the item text as a null-terminated string, but limit the number of characters 
copied, including the null termination character, to this value, which must be greater 
than 0. | 
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param2_ 


pszitemText (PSZ) | 
Buffer into which the item text is to be copied. 


This points to a string (character) buffer. 


Returns 
sTextLength (SHORT) 
Length of item text. 


The length of the text string, excluding the null termination character. 


0 Error occurred. For example, no item of the specified identity exists or the item 
has no text. No text is copied. 


Other Length of item text. 


Remarks 

The menu control window procedure responds to this message by copying up to smaxcount 
characters as a null-terminated string from the text of the item specified by usitem, if it has 
the style MIS_TEXT, into the buffer specified by psz/temText. 


The length of the item text can be determined by using the MM_QUERYITEMTEXTLENGTH 
message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sTextLength to the default value of 0. 


MM_QUERYITEMTEXTLENGTH 


This message returns the text length of the specified menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identifier. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
sLength (SHORT) 
Length of item text. 


The length of the text string, excluding the null termination character. 


0 Error occurred. For example, no item of the specified identity exists or the item 
has no text. No text is copied. 


Other Length of item text. 


Remarks 
The menu control window procedure responds to this message by returning the length in 
characters of the text of the identified item, if it has a style of MIS_TEXT. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sLength to the default value of 0. 


MM_QUERYSELITEMID 


This message returns the identity of the selected menu item. 


Parameters 
param1 


usReserve (USHORT) | 
Reserved value, should be 0. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for a selected item with the 
specified identifier. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for a selected item with 
the specified identifier. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
sresult (SHORT) 
Selected item identifier. 


MiID_ERROR ~ Error occurred ° 
MIT_NONE No item selected 
Other Selected item identifier. 


Remarks 

The menu control window procedure responds to this message by returning the identity of 
the selected item in the menu. Submenus and subdialogs are not searched unless 
usincludesubmenus is set to TRUE. 


Default Processing | | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set sresult to the default value of 0. 


MM_REMOVEITEM 


This message removes a menu item. 


Parameters 
param 


usitem (USHORT) 
Item identifier. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and delete it. 

FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sitemsLeft (SHORT) 
Count of remaining items. 
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Remarks 

The menu control window procedure responds to this message by removing the identified 
item from the menu and setting s/temsLeft to the count of items in the menu after the item is 
deleted. 


The difference between this message and MM_DELETEITEM is that MM_DELETEITEM 
destroys any submenu window, and deletes any bit map associated with the item, whereas 
MM_REMOVEITEM does not. — 


Note: It must be sent, not posted, to the menu control. 


Default Processing | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set s/temsLeft to the default value of 0. 


MM_SELECTITEM 


This message selects or deselects a menu item. 


Parameters 
param1 


sitem (SHORT) 
Item identifier. 


MIT_NONE _ Deselect all the items in the menu. 
Other Item identifier. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and select or deselect it. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


usReserve (USHORT) 
Reserved value, should be 0. 


usdismissed (USHORT) 
Dismissed flag. 


TRUE Dismiss the menu 
FALSE Do not dismiss the menu. 
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Returns 
rc (BOOL) 
Success indicator. 


TRUE A selection has been rade: or sitem is MIT_NONE. 
FALSE A selection has not been made, or a deselection has been made, or t sitem is 
not MIT_NONE. 


Remarks 

The menu control window procedure responds to this message by setting the selection state 
of the (Sub)menu which contains the specified item to indicate that the item is selected or 
deselected. If usincludesubmenus is set to TRUE, the selection state of the (sub)menu 
owning the submenu which contains the specified item is also set. This process continues up 
the menu hierarchy until the top level menu is reached. 


If an item is selected, and usdismissed is set to TRUE, a WM_COMMAND, 
WM_SYSCOMMAND, or WM_HELP message, as appropriate, is posted to the owner, and 
the menu is dismissed. 


Note: This message must be sent, not posted, to the menu control. 
Default Processing 


The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


MM_SETDEFAULTITEMID 


This message is used to set the default item in a conditional cascade menu. 


Parameters 
param1 


ulDefitemID (ULONG) 
The menu id of the item to become the new default. 


param2 


ulReserved (ULONG) 
Reserved value, must be 0. 


Returns 
re (BOOL) 
Success of failure indicator. 


TRUE The conditional cascade default was set. 
FALSE ‘The conditional cascade default was not set. 
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Remarks 
The default item is the menu-id that will be returned if the main menu option is clicked on. 


Icon 
*Tree 
Details 


id=MID_ICON 
id=MID_TREE 
id=MID_DETAILS 


In the example above, where MID_TREE is currently the default, if the user clicked on the 
“Open” option without opening the conditional cascade menu, the menu would send back a 
notification that MID_TREE was selected. 


Default Processing 
The default window procedure takes no action other than to return 0. 


MM_SETITEM 


This message sets the definition of a menu item. 


Parameters 
param 


usReserve (USHORT) 
Reserved value, should be 0. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and set its definition. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


pmenuitem (PMENUITEM) 
Menu-item data structure. 


This points to a MENUITEM structure. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Chapter 15. Menu Control Window Processing 15-25 


Remarks 
The menu control window procedure responds to this message by using the specified 
structure to update the definition of the identified menu item. 


The /Position field of the structure specified by pmenuitem is ignored, as the position of the 
item cannot be changed by use of this message. 


Note: It must be sent, not posted, to the menu control. . 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


MM_SETITEMATTR 


This message sets the attributes of a menu item. 


Parameters 
‘param 


usitem (USHORT) 
Item identifier. 


usincludesubmenus (USHORT) 
Include submenus indicator. 


TRUE If the menu does not have an item with the specified identifier, search the 
submenus and subdialogs of the menu for an item with the specified 
identifier and set its attributes. 


FALSE _ If the menu does not have an item with the specified identifier, do not 
search the submenus and subdialogs of the menu for an item with the 
specified identifier. 


param2 


usattributemask (USHORT) 
Attribute mask. 


uSattributedata (USHORT) 
Attribute data. 


Returns 
re (BOOL) 
Success indicator. . 


TRUE Successful completion 
FALSE — Error occurred. 
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Remarks 
The menu control window procedure responds to this message by setting the state of the 
specified attributes for the identified item. 


Note: it must be sent, not posted, to the menu control. 


Default Processing | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


Examples 

This example sends an MM_SETITEMATTR message to set the IDM_LARGE menu item’s 
state to checked, and then sends another MM_SETITEMATTR message to set the 
IDM_MEDIUM menu item’s state to unchecked. 


MM_SETITEMHANDLE 


This message sets the handle of a menu item. 


Parameters 
param1 


usitem (USHORT) 
Item index. 


param2 


ulitemhandle (ULONG) 
Item handle. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 
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Remarks 
The menu control window procedure responds to this message by setting the handle of the 
indexed menu item. 


This is used to set a handle for menu items that have a style of MIS_ BITMAP or 
MIS_OWNERDRAW. . 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


MM_SETITEMTEXT 


This message sets the text of a menu item. 


Parameters 
param1 


usitem (USHORT) 
Item identifier. 


param2 


pszitemText (PSZ) 
Item text. 


This points to a string containing the text to set the menu item to. 


- Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The menu control responds to this message by setting the text of the identified item, if it has 
a style of MIS_TEXT, using the specified null-terminated string. 


Note: It must be sent, not posted, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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MM_STARTMENUMODE 


This message is used to begin menu selection. 


Parameters 
param1 


usshowsubmenu (USHORT) 
Show submenu flag. 


TRUE Show the submenu (pull-down menu) of the selected action bar item 
when the menu enters selection mode. If the action bar is not visible, the 
submenu is shown, otherwise it is not shown. If the item selected does 
not have a submenu, this parameter is ignored. 


FALSE Do not show the submenu (pull-down menu) of the selected action bar 
item when the menu enters selection mode. 


usresumemenu (USHORT) 
Resume menu mode flag. 


TRUE Resume the user interaction with the menu from where it left off. The 
menu is assumed to have been used previously and left without 
dismissing one of the submenus, and therefore is resumed in that 
submenu. 


FALSE Begin user interaction with the menu from the action bar, subject to the 
value of the usshowsubmenu parameter. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
It is posted to the menu when the operator presses the menu key. 


Note: It must be posted, not sent, to the menu control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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WM_QUERYCONVERTPOS (in Menu Controls) 
For the cause of this message, see “WM_QUERYCONVERTPOS’ on page 10-72. 


For a description of the parameters, see “WM_QUERYCONVERTPOS?’ on page 10-72. 


Remarks 
The menu control window procedure returns QCP_NOCONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS’ on page 10-72. 


Related Messages 
e WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in Menu Controls) 


“Occurs when an application queries the menu control window procedure parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Remarks 
The menu control window procedure responds to this message by passing it to the default 
window procedure. 


Default Processing 
The default window procedure sets the cchText, cbPresParams, and cbCtiData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to 0 and sets rc to FALSE. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 


WM_SETWINDOWPARAMS (in Menu Controls) 


This message occurs when an application sets or changes the menu control window 
procedure parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS” on page 10-86. 


Remarks 
The menu control window procedure responds to this message by passing it to the default 
window procedure. 


Default Processing 
The default window procedure takes no action on this Meeoe other than to set rc to 
FALSE. 
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Related Messages 
¢ WM_SETWINDOWPARAMS 


WM_SYSCOMMAND 
For the cause of this message, see “WM_SYSCOMMAND?” on page 10-91. 
For a description of the parameters, see “WM_SYSCOMMAND?” on page 10-91. 


The menu control window procedure sets uscmd to the menu-item identity. 


Remarks 

The menu control window procedure generates this message and posts it to the queue of its 
owner, when an item is selected that has the style of MIS_SYSCOMMAND, but only if the 
WM_MENUSELECT (in Menu Controls) message returns a rc of TRUE. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 
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Chapter 16. Multi-Line Entry Field Control Window 
Processing 


This system-provided window procedure processes the actions on a multi-line entry field 
contro! (WC_MLE). 


Purpose 
A multi-line entry field control is a rectangular window that displays multiple lines of text that 
the operator can edit. When it has the focus, the cursor marks the current insertion or 
replacement point. 


How to Use 
The text is displayed within a rectangular window. Scroll bars appear if requested. 


On all four sides of the text within the window there exists a thin margin area. This margin 
remains drawn in the window’s background color, and characters are never drawn into this 
margin. Mouse events that occur in the margin are processed differently from mouse events 
that occur in the text area. The margin should be large enough to be easily clicked on, but 
not so large as to take up a large quantity of screen space. It is suggested, but not required, 
that the left and right margins be half the average character width of the system font, and 
that the top and bottom margins be half the maximum baseline extent of the system font. 


Text is defined as a stream of characters, with hard line-break characters in the text. 
Between any two bytes in the text stream, and at either end of the document, there is an 
insertion point. Note that in a DBCS environment, it is possible to have an insertion point in 
the middle of a DBCS character. If such an insertion point is specified in a function, the 
function will either round the insertion point in a sensible way, or the function will fail with an 
error code indicating the problem. 


The text always contains a selection region, defined by an anchor point and a cursor point. 
The anchor and cursor points are insertion points. If the MLE window has the focus, the text 
between these two points is drawn highlighted and the cursor point is indicated by a flashing 
text cursor. The selection region can be affected by some import/export operations. 


The cursor point and the anchor point define the range of the selection. These two points 
are often the same, in which case no text is selected and only a text cursor (but no 
highlighting) is displayed. A user can use SHIFT+cursor movement combinations to extend 
the selection, which leaves the anchor point alone, and moves the cursor point to a new 
position in the document. 


The MLE has three modes: 


READ-ONLY The keyboard user interface disallows any operations that would change 
the content of the text, although applications using the MLE can still 
change the text contents. The application can query this mode, in order 
that it can disallow application-specific operations. 
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WORD-WRAP When this mode is in effect, soft line-breaks are inserted into the text at 
word boundaries so that the user need not scroll the display horizontally 
to see all the text. When this mode is off, text is allowed to trail off the 
right-hand edge of the window. 


INSERT/OVERTYPE This mode determines whether keystrokes are inserted into the text, or 
whether they overtype existing text. Unlike the other two modes, this 
mode is maintained by the system. The MLE must merely be aware of 
the system mode. 

Notes: 


1. The MLE is intended for text under 4Kb in size. Performance will be fast for text up to 
32KB in size. Text greater than this will be supported but performance may not be 
acceptable. 


2. In this chapter ‘CR’ denotes Carriage-return, and ‘LF’ denotes line-feed. 


Multi-Line Entry Field Control Styles 
These multi-line entry field control styles are available: 
MLS_BORDER A thin border is drawn around the multi-line entry field window. 
MLS_READONLY The multi-line entry field is initially in read-only mode. 
MLS _WORDWRAP The multi-line entry field initially word-wraps text. 
MLS_HSCROLL The multi-line entry field displays and handles a horizontal scroll bar. 
MLS_VSCROLL The multi-line entry field displays and handles a vertical scroll bar. 


MLS_IGNORETAB The multi-line entry field ignores tab key strokes. It passes the . 
appropriate WM_CHAR to its owner window. 


MLS_DISABLEUNDO The multi-line entry field will not allow undo actions. 


Multi-Line Entry Field Control Data 
See “MLECTLDATA’” on page A-127. 
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Multi-Line Entry Field Control Notification Messages 


This message is initiated by the multi-line entry field window procedure to notify its owner of 


significant events. 


WM_CONTROL (in Multiline Entry Fields) 
For the cause of this message, see “WM CONTROL” on page 10-39. 


Parameters 
param1 


usid (USHORT) 
Control window identity. 


usnotifycode (USHORT) 
Notify code. 


MLN_TEXTOVERFLOW 


MLN_PIXHORZOVERFLOW 


A key stroke causes the amount of text to exceed 
the limit on the number of bytes of data (refer to 
MLM_SETTEXTLIMIT). The parameter contains the 
number of bytes of data which would not fit within 
the current text limit. For character key strokes this 
can be 1 or 2 (DBCS). For Shift+Ins (paste) it can 
be any amount up to the paste limit. 


The default rc of FALSE causes the default error 
handling, which is to ignore the key stroke, and 
beep. 


An re of TRUE implies that corrective action has 
been taken (such as deleting existing text or raising 
the limit) and the WM_CHAR (in Multiline Entry 
Fields) should be reprocessed as if just entered. 


A key stroke causes the size of the display bit map 

to exceed the horizontal limit of the format rectangle 
(refer to MLM_SETFORMATRECT). The parameter 
contains the number of pels that would not fit within 
the current text limit. 


The default rc of FALSE causes the default error 
handling, which is to ignore the key stroke, and 
beep. 


An rc of TRUE implies that corrective action has 
been taken (such as. changing to a smaller font or 
raising the limit) and the WM_CHAR (in Multiline 
Entry Fields) should be reprocessed as if just 
entered. 
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MLN_PIXVERTOVERFLOW 


MLN_OVERFLOW 


MLN_HSCROLL 


MLN_VSCROLL 


MLN_CHANGE 


MLN_UNDOOVERFLOW 
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A key stroke causes the size of the display bit map 
to exceed the vertical limit of the format rectangle 
(refer to MLM_SETFORMATRECT). The parameter 
contains the number of pels that would not fit within 
the current text limit. 


The default rc of FALSE causes the default error 
handling, which is to ignore the key stroke, and 
beep. 


An rc of TRUE implies that corrective action has 
been taken (such as changing to a smaller font or — 
raising the limit) and the WM_CHAR (in Multiline 
Entry Fields) should be reprocessed as if just 
entered. 


An action other than entry of a key stroke causes a 
condition involving the text limit or format rectangle 
limit, such that either the limit becomes inadequate 
to contain the text or the text exceeds the limit. 


This can be caused by: 


MLM_SETWRAP 
MLM_SETTABSTOP 
MLM_SETFONT 
MLM_IMPORT 
MLM_PASTE 
MLM_CUT 
MLM_UNDO 
MLM_DELETE 

WM_ SIZE. 


Indicates that the MLE has completed a scrolling 
calculation and is about to update the display 
accordingly. All queries return values as if the 
scrolling were complete. However, no scrolling 
action is visible on the user interface. 


Indicates that the MLE has completed a scrolling 
calculation and is about to update the display 
accordingly. All queries return values as if the 
scrolling were complete. However, no scrolling 
action is visible on the user interface. 


Signals that the text has changed. This notification 
is sent whenever any text change occurs. 


Signals that the text change operation, which could 
normally be undone, cannot be undone because the 
amount of text involved exceeds the undo capability. 
This includes text entry, deletion, cutting, and 
pasting. 


MLN_CLPBDFAIL 
MLN_MEMERROR 


MLN_SETFOCUS 
MLN_KILLFOCUS 


MLN_MARGIN 


MLN_SEARCHPAUSE 


param2 


ulOver (ULONG) 


Number of bytes that do not fit. 


Signals that a clipboard operation failed. 


Signals that the required storage cannot be 
obtained. The action that results in the increased 
storage requirement fails. 


Sent whenever the MLE window receives the input 
focus. 


Sent whenever the MLE window loses the input 
focus. 


Whenever the user moves the mouse into the left, 
right top, or bottom margins, this message is sent to 
the owner of the window. 


lf the owner returns an rc of TRUE, the mouse 
move is assumed to have been processed by the 
owner and no further action need be taken. 


If the owner returns an rc of FALSE, the MLE 
performs a default action appropriate to each 
different mouse action. 


The exceptions to this are all mouse messages that 
occur after a button-down inside the margin, until 
and including the matching button-up. Conceptually 
the drag (button-down until button-up) is a single 
macro event. Therefore, if FALSE is returned for a 
button-down event, no further margin notifications 
are given until after the drag has ended (button-up). 


Note: If the application receives a notification of 
button-down in the margin and processes it, 
it must capture the mouse until the button-up 
event. 


This notification is sent periodically by the MLE, 
while an MLM_SEARCH message is being 
processed, to give an application the opportunity to 
stop excessively long searches, and to provide 
search progress information. The owner window 
can respond either with TRUE or FALSE. FALSE 
causes the MLE to continue searching; TRUE 
causes the MLE to stop the search immediately. 
For further information, see MLM_SEARCH 


param2 contains ulOver for a usnotifycode of MLN_TEXTOVERFLOW. 
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pixOver (PIX) 


Linear distance of overflow in pels. 


param2 contains pixOver for a usnotifycode of MLN_PIXHORZOVERFLOW or 
MLN_PIXVERTOVERFLOW. 


pErrinfo (POVERFLOW) 


Overflow error information structure. 
param2 contains pErrinfo for a usnotifycode of MLN_OVERFLOW. 
The afErrind field of the MLEOVERFLOW structure can take one or more of the 


following values: 


MLFEFR_RESIZE 


MLFEFR_TABSTOP 


MLFEFR_FONT 


MLFEFR_WORDWRAP 


MLFEFR_TEXT 
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The window is resized, and the format rectangle is tied to 
the window size and limited either horizontally, vertically, 
or both. The implicit change of the format rectangle to the 
new size does not contain the text. The format rectangle 
is made static at the previous size, and the 
MLESFR_MATCHWINDOW style is turned off until set 
again by the application. This is done in response to a 
WM_SIZE message, and therefore the multi-line entry 
field does not forward the return value from this 
notification message. 


A tab stop location change is requested, and the text is 
limited either horizontally, vertically, or both. Changing 
the tab stops causes the text to exceed the limit. The tab 
stop change is rejected. 


A font change is requested, and the text is limited either 
horizontally, vertically, or both. Changing the font causes 
the text to exceed the limit. The font change is rejected. 


The word-wrap state is requested to be changed, and the » 
text is limited either horizontally, vertically, or both. 
Wrapping the text differently exceeds the limit, and the 
request is rejected. This happens in situations where the 
horizontal limit is not set, there are lines exceeding it, and 
word-wrap is being changed from off to on, such that it 
creates soft line breaks resulting in increased vertical size. 
This happens if word-wrap is being changed from on to 
off, and there is at least one line created by a soft 
line-break, such that when that line-break is removed, the 
full line (up to the hard line break) exceeds the horizontal 
limit. 

Text is changed by MLM_IMPORT, MLM_PASTE, 
MLM_CUT, MLM_UNDO, or MLM_DELETE, and the text 
is limited either horizontally, vertically, or both within the 
format rectangle. The change causes the text to exceed 
the format rectangle in a dimension that is limited. For 


example, Delete and EOL joins text from two lines into 
one line long enough to exceed the horizontal limit. 


MLFETL_TEXTBYTES Text is changed by MLM_IMPORT MLM_PASTE, or 
MLM_UNDO, and the text is limited to a maximum 
number of bytes. The change causes the text to exceed 
that maximum. 


ulErrind (ULONG) 
Clipboard fail flag. 
param2 contains ulErrind for a usnotifycode of MLN_CLPBDFAIL. 


MLFCPBD_TOOMUCHTEXT Text amount exceeds clipboard capacity 
MLFCPBD_CLPBDERROR A clipboard error occurred. 


pmrg (PMARGSTRUCT) 
Margin structure. 
param2 contains pmrg for a usnotifycode of MLN_MARGIN. 


The left and right margins are defined .as going all the way to the top and bottom 
such that the top and bottom margins are contained between them. Therefore, the 
corners are included in the sides. 


usMouMsg contains the mouse message that signals the event. 


iptNear contains the insertion point of the nearest point in the text. For situations 
where the nearest location is beyond the end of a line, the insertion point for the 
end of the line is returned. (The EOL character is considered to be beyond the end 
of the line.) . 


iptSearchedTo (IPT) 

Current insertion point of search. 

param2 contains iptSearchedTo for a usnotifycode of MLN_SEARCHPAUSE. 
ulReserved (ULONG) 

Reserved value, should be 0. 


param2 contains ulReserved for a usnotifycode of MLN_HSCROLL, 
MLN_VSCROLL, MLN_CHANGE, MLN_UNDOOVERFLOW, MLN_MEMERROR, 
MLN_SETFOCUS, or MLN_KILLFOCUS. 
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Returns 
ReturnCode 


re (BOOL) 
Action taken by application. 


ReturnCode contains rc for a usnotifycode of MLN_TEXTOVERFLOW, _ 
MLN_PIXHORZOVERFLOW, MLN_PIXVERTOVERFLOW, MLN_MARGIN, or 
MLN_SEARCHPAUSE. 


TRUE ~~ The multiline entry field control assumes that appropriate action has been 
taken by the application. Appropriate action depends on the MLN_* 
notification code, and is documented under the usnotifycode field. 


FALSE The multiline entry field control assumes that the application has ignored 
this WM_CONTROL (in Multiline Entry Fields) message, and takes action 
appropriate to the MLN_* notification code, as documented under the 
usnotifycode field. 


ulReserved (ULONG) 
Reserved value, should be 0. 


ReturnCode contains ulReserved for a usnotifycode of MLN_OVERFLOW, 
MLN_HSCROLL, MLN_VSCROLL, MLN_CHANGE, MLN_UNDOOVERFLOW, 
MLN _CLPBDFAIL, MLN_MEMERROR, MLN _SETFOCUS, or MLN_KILLFOCUS. 


Remarks 


The multiline entry field control window procedure generates this message and sends it to its 
owner, informing the owner of the event. 


param2 depends on the MLN_* notification code. 


Default Processing 


The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢* WM_CONTROL 
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Multi-Line Entry Field Window Messages 


This section describes the multi-line entry field control window procedure actions on receiving 
the following messages. a 


MLM_CHARFROMLINE 


This message returns the first insertion point on a given line. 


Parameters 
param1 


ILineNum (LONG) 
Line number of interest. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
iptFirst (IPT) 


First insertion point on line. 


Remarks 
For any line number, the insertion point just before the first character on that line is returned. 
If the line number is -1, the line containing the cursor is used. 


The term line means a line on the display after the application of word-wrap. It does not 
mean a line as defined by the CR LF line-break sequence. 


Default Processing 
The default window procedure takes no action on this message, other than to set /ptFirst to 
0. 


MLM_CLEAR 


This message clears the current selection. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) : 
Reserved value, should be 0. 


Returns 
ulClear (ULONG) 
Number of bytes deleted, counted in CF_TEXT format. 


Remarks 
The multi-line entry field control window procedure responds to this message by clearing the 
current selection and returning the number of bytes cleared. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Clear to 
0. 


MLM_COPY 


This message copies the current selection to the clipboard. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulCopy (ULONG) 
Number of bytes transferred, counted in CF_TEXT format. 


Remarks 

The multi-line entry field control window procedure responds to this message by copying the 
selected text to the clipboard. The text is translated to standard clipboard format, which is 
the same as exporting with MLE_CFTEXT format. 


The text is placed on the clipboard as a single contiguous data segment. This restricts the 
amount to the maximum segment size (64KB). 
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This may cause an overflow, see MLN_OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Copy to 
0. 


MLM_CUT 


This message copies the text that forms the current selection to the clipboard and then 
deletes it from the MLE control. 


Parameters | 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulCopy (ULONG) 
Number of bytes transferred, counted in CF_TEXT format. 


Remarks 

The multi-line entry field control window procedure responds to this message by copying the 
selected text to the clipboard and then deleting it. The text is translated to standard 
clipboard format, which is the same as exporting with MLE_CFTEXT format. 


The text is placed on the clipboard as a single contiguous data segment. This restricts the 
amount to the maximum segment size (64KB). 


This may cause an overflow, see MLN_OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Copy to 
0. 
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MLM_DELETE 


This message deletes text. 


Parameters 
param1 


iptBegin (IPT) 
Starting point of deletion. 


param2 


ulDel (ULONG) 
Number of bytes to delete. 


Returns 
ulSuccess (ULONG) 
Number of bytes successfully deleted. 


Remarks | 

This message takes an insertion point and a length, and deletes that number of characters 
from the text. If the insertion point is -1, the selection is used and the effect is identical to 
the MLM_CLEAR message. : 


This may cause an overflow, see MLN_OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulSuccess 
to 0. 


MLM_DISABLEREFRESH 


This message disables screen refresh. _ 


Parameters 
param 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


16-12 PM Programming Reference Vol II 


Returns 
re (BOOL) 
Success indicator. 


TRUE — Successful completion. 
‘FALSE — Error occurred. 


Remarks 

This message disables screen refreshes. This allows an application to make changes 
throughout a document while avoiding unnecessary overhead caused by attempts to keep 
the screen display current. When an MLM_ENABLEREFRESH message is sent, the screen 
display is brought up to date with the contents of the text. 


While refresh is disabled, mouse and keyboard messages are processed by beeping and 
ignoring them, except for mouse moves, which do not beep; the mouse pointer changes to 
the system standard wait symbol (a clock face). 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_ENABLEREFRESH 


This message enables screen refresh. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


O Reserved value, 0. 
Returns 


re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE An error occurred. 


Remarks ) 
This message enables screen refreshes. This allows an application to make changes 
throughout a document while avoiding unnecessary overhead caused by attempts to keep 
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the screen display current. When an MLM_ENABLEREFRESH message is sent, the screen 
display is brought up to date with the contents of the text. 


_ While refresh is disabled, mouse and keyboard messages are processed by beeping and 
ignoring them, except for mouse moves, which do not beep; the mouse pointer changes to 
the system standard wait symbol (a clock face). 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_EXPORT 


This message exports text to a buffer. 


Parameters 
param1 


pBegin (PIPT) 
Starting point. 


Updated to follow the last character exported. 


param2 


pCopy (PULONG) 
Number of bytes being exported. 


Decremented by the number of bytes actually exported. 


Returns 
ulSuccess (ULONG) 
Number of bytes successfully exported. 


Remarks 

This message takes an insertion point and length as parameters, and copies text, starting 
from that insertion point, into the buffer set by MLM_SETIMPORTEXPORT. Text is in the 
format set by MLM_FORMAT. If the insertion point is -1, the selection is used for both 
pBegin and pCopy. 


On return, pBegin is updated to follow the last byte exported, and the number of bytes to be 
exported is decremented by the number actually exported. This is done to prepare those — 
parameter values for the next export. The return value indicates the number of bytes - 
actually put into the buffer. This number is less than, or equal to, the buffer size (see 
MLM_SETIMPORTEXPORT). 
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Note: All exports are done in full characters. Therefore, if either the length of the buffer or 
the number of bytes to be exported result in the last byte transferred being only half 
of a DBCS character, the MLE will not transfer that byte. 


It returns the number of bytes placed in the export buffer. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Success 
to 0. 


MLM_FORMAT 


This message sets the format to be used for buffer importing and exporting. 


Parameters 
param1 


usFormat (USHORT) 
Format to be used for import and export. 


MLFIE_CFTEXT Text format. Each line ends with a carriage-return/line-feed 
combination. Tab characters separate fields within a line. A 
NULL character signals the end of the data. 


MLFIE_NOTRANS _ Uses LF for line delineation, and guarantees that any text 
imported into the MLE in this format can be recovered in 
exactly the same form on export. 


MLFIE_WINFMT (Windows MLE format.) On import, recognizes CR LF as 
denoting hard line-breaks, and ignores the sequence CR 
CR LF. On export, uses CR LF to denote a hard line-break 
and CR CR LF to denote a soft line-break caused by 
word-wrapping. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usFormat (USHORT) 
Previous format value. 


Remarks 
The default format is MLFIE_CFTEXT. 


The keyword MLFIE_RTF is reserved. 
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Default Processing 
The default window procedure takes no action on this message, other than to set usFormat 
to 0. 


MLM_IMPORT 


This message imports text from a buffer. 


Parameters 
param1 


pBegin (PIPT) 
Insertion point. 


Updated to insertion point following last insert. 


param2 


ulCopy (ULONG) 
Number of bytes in buffer. 


Returns 
ulSuccess (ULONG) 
Number of bytes successfully inserted. 


Remarks 

This message takes an insertion point and length as parameters. It assumes a buffer has 
been set using MLM_SETIMPORTEXPORT, and inserts the contents of the buffer at the 
insertion point in the text. The contents are interpreted as being in the format set by 
MLM_FORMAT. If the insertion point is -1, the cursor point is used. 


The insertion point pBegin is updated by the MLE to the point after the last character 
imported. This provides the application with the location for the next import. 


The return value indicates how many bytes were actually transferred. 


All imports are done in full characters, therefore, if the number of bytes to be imported results 
in the last byte transferred being only half of a DBCS character, or part of a line-break 
sequence (CR LF or CR CR LF), the MLE does not transfer that byte. If the return value 
indicates that less than the full amount was transferred, a check must be made to determine 
if it is the beginning of a multi-byte sequence, and if so, the parts must be mated and 
imported as a whole. 


This can cause an overflow, see MLN_OVERFLOW. 


Note: The buffer is not zero-terminated; NULL characters can be inserted into the text. 
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Default Processing 
The default window procedure takes no action on this message, other than to set u/Success 
to 0. 


MLM_INSERT 


This message deletes the current selection and replaces it with a text string. 


Parameters 
param1 


pchText (PCHAR) 
Null-terminated text string. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulCount (ULONG) 


Number of bytes actually inserted. 


Remarks 

This message inserts the text string at the current selection, deleting that selection in the 
same manner as typing at the keyboard would. The text string must be in CF_TEXT format 
(or one of the formats acceptable to MLM_IMPORT) and null-terminated. The line-break 
(CR LF, LF, and so on) is counted as one byte, regardless of the number of bytes occupied 
in the buffer, and the null terminator is not counted. 


This interacts with the format rectangle and text limits, and a return of less than the full count 
can be the result. If so, a notification message is sent. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Count to 
0. 
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MLM_LINEFROMCHAR 


This message returns the line number corresponding to a given insertion point. 


Parameters 
param1 


iptFirst (IPT) 
Insertion point of interest. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ILineNum (LONG) 
Line number of insertion point. 


Remarks 
For any insertion point, the corresponding line number is returned. If the insertion point is 
-1, the number of the line containing the first insertion point of the selection is returned. 


The term line means a line on the display after the application of word-wrap. It does not 
mean a line as defined by the CR LF line-break sequence. 


Default Processing 
The default window procedure takes no action on this message, other than to set /LineNum 
to 0. 


MLM_PASTE 


This message replaces the text that forms the current selection, with text from the clipboard. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ulCopy (ULONG) 
Number of bytes transferred, counted in. CF_TEXT format. 


Remarks 

The multi-line entry field contro! window procedure responds to this message by replacing 
the selected text with text from the clipboard. The text is translated from standard clipboard 
format, which is the same as importing with MLE_CFTEXT format. 


The text is assumed to be in the clipboard as a single contiguous data segment. This 
restricts the amount to the maximum segment size (64Kb). 


This can cause an overflow, see MLN_OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Copy to 
0. 


MLM_QUERYBACKCOLOR 


This message queries the background color. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
IColor (LONG) 
Text color. 


Remarks 
This message returns the color in which the background is to be drawn. 


The color values are the same as those used by GpiSetColor. 


Default Processing 
The default window procedure takes no action on this message, other than to set /Color to 0. 
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MLM_QUERYCHANGED 


This message queries the changed flag. 


Parameters 
param 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Current changed status. 


TRUE — Text has changed since the last time that the change flag was cleared. 
FALSE Text has not changed since the last time that the change flag was cleared. 


Remarks 
The multi-line entry field control window procedure responds to this message by returning the 
changed flag for the text without altering it. See also MLN_CHANGE. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 0 
(FALSE). 


MLM_QUERYFIRSTCHAR 


This message queries the first visible character. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
iptFVC (IPT) 
First visible character. 


Remarks 

Returns the insertion point immediately preceding the character visible in the upper left-hand 

corner of the screen. If a partial character is displayed, that character counts as the first 

visible character. 

Note: !n situations where no character is visible, because the text is scrolled to the right 
beyond the end of the top line, this returns the insertion point of the last character on 
the line (EOL not considered). In situations where there are no characters on the 
line, the insertion point at the beginning is returned. 


Default Processing 
The default window procedure takes no action on this message, other than to set jptFVC to 


0. 


MLM_QUERYFONT 


This message queries which font is in use. 


Parameters 
param1 


pFattrs (PFATTRS) 
Font attribute structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
System font indicator. 


TRUE _ The system font is in use. 
FALSE The system font is not in use. 


Remarks 
This message puts the attributes of the current drawing font into the font attribute structure. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 
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MLM_QUERYFORMATLINELENGTH 


This message returns the number of bytes to end of line after formatting has been applied. 


Parameters 
param 


iptStart (IPT) 
Insertion point to count from. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
iptLine (IPT) 
Count of bytes to end of line. 


Remarks 

For any insertion point, the number of bytes between that insertion point and the end of the 
line is returned, after the current formatting is applied. If the insertion point is -1, the cursor 
position is used. This message differs from MLM_QUERYLINELENGTH in that the byte 
count returned reflects the effects of the current formatting set by MLM_FORMAT. 


Default Processing 
The default window procedure takes no action on this message, other than to set jptLine to 
0. 


MLM_QUERYFORMATRECT 


This message queries the format dimensions and mode. 


Parameters 
param1 


pFormatRect (PPOINTL) 


Format dimensions. 


The size of the current limiting dimensions. 
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param2 


flFlags (ULONG) 
Flags governing interpretation of dimensions. 


An array of MLFFMTRECT_* flags defined under the fiFlags field of the 
MLM_SETFORMATRECT message. 


Returns 
ulReserved (ULONG) 
Reserved value. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


MLM_QUERYFORMATTEXTLENGTH 


This message returns the length of a specified range of characters after the current 
formatting has been applied. 


Parameters 
param1 


iptStart (IPT) 
Insertion point to start from. 


param2 


ulScan (ULONG) 
Number of characters to convert to bytes. 


OxFFFFFFFF Convert until end of line 
other Convert specified number of characters. 


Returns 
ulText (ULONG) 
Count of bytes in text after formatting. 
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Remarks | 
This message returns the length in bytes of a range of characters after the current formatting 
is applied. This differs from MLM_QUERYTEXTLENGTH in that: 


e A range of insertion points can be queried. 


e The byte count returned reflects the effects of the current formatting set by 
MLM_FORMAT. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Text to 0. 


MLM_QUERYIMPORTEXPORT 


This message queries the current transfer buffer. 


Parameters 
param1 


Buff (PVOID *) - 
Transfer buffer. 


param2 


pulLength (PULONG) 
Size of transfer buffer in bytes. 


Returns 
re (ULONG) 
Success indicator. 


TRUE Successful completion. 
FALSE _ Error occurred. 


Remarks 
This message returns the values from the most recent MLM_SETIMPORTEXPORT, or 0 for 
either value if it has not been set. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 0 
(FALSE). 
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MLM_QUERYLINECOUNT 


This message queries the number of lines of text. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulLines (ULONG) 
The number of lines of text. 


Remarks 
The term line means a line on the display after the application of word-wrap. It does not 
mean a line as defined by the CR LF line-break sequence. 


The multi-line edit control always maintains one CR LF line-break in the buffer, therefore the 
number of lines returned may be one greater than the number actually visible. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Lines to 
0. 


MLM_QUERYLINELENGTH 


This message returns the number of bytes between a given insertion point and the end of 
line. 


Parameters 
param 


iptStart (IPT) 
Insertion point to count from. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
iptLine (IPT) 
Count of bytes to end of line. 


Remarks 

For any insertion point, the number of bytes between that insertion point and the end of the 
line is returned. If the insertion point is -1, the cursor position is used. If the line contains a 
hard line-break, it is counted as one byte. 


The term line means a line on the display after the application of word-wrap. It does not 
mean a line as defined by the CR LF line-break sequence. 


Default Processing 
The default window procedure takes no action on this message, other than to set jptLine to 
0. 


MLM_QUERYREADONLY 


This message queries the read-only mode. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Current read-only status. 


TRUE Read-only mode is set. 
FALSE Read-only mode is cleared. 
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Default Processing 


The default window procedure takes no action on this message, other than to set rc to 


FALSE. 


MLM_QUERYSEL 


This message returns the location of the selection. 


Parameters 
param1 


usQueryMode (USHORT) 
Query Mode. 


MLFQS_MINMAXSEL Return both minimum and maximum points of selection in 
a format compatible with the EM_QUERYSEL message. 


MLFQS_MINSEL Return minimum insertion point of selection. 
MLFQS_MAXSEL Return maximum insertion point of selection. 
MLFQS_ANCHORSEL Return anchor point of selection. 
MLFQS_CURSORSEL Return cursor point of selection. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


sMinSel (SHORT) 
Minimum insertion point of selection. 


This value is rounded down to 65 535, if necessary. 


ReturnCode contains sMinSel and sMaxSel for a usQueryMode of 
MLFQS_MINMAXSEL. 


sMaxSel (SHORT) 
Maximum insertion point of selection. 


This. value is rounded down to 65 535 if necessary. 


ReturnCode contains sMinSel and sMaxSel for a usQueryMode of 
MLFQS_MINMAXSEL. 
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ipt (IPT) 
Requested insertion point. 


ReturnCode contains ipt for a usQueryMode of MLFQS_MINSEL, 
MLFQS_MAXSEL, MLFQS_ANCHORSEL, or MLFQS_CURSORSEL. 


Remarks 

This message returns the location of the selection in several different forms. The insertion 
points lie between characters, and start at a zero origin before the first character in the MLE. 
Subtracting the minimum from the maximum gives the number of characters in the selection. 
This is not necessarily the number of bytes of ASCII. The line-break character is a CR LF (2 
bytes) and all DBCS characters are 2 bytes. To determine the number of bytes, use 
MLM_QUERYFORMATTEXTLENGTH, being sure that the format choice set by 
MLM_FORMAT is set to what is used when the data is exported from the MLE (for example, 
MLE_CFTEXT for MLM_QUERYSELTEXT). 


Note the following: 


e If anchor point > cursor point, minimum point = cursor point and maximum point = 
anchor point. 


e If anchor point < cursor point, minimum point = anchor point and maximum point = 
cursor point. 


Default Processing 
The default window procedure takes no action on this message, other than to set 
ReturnCode to 0. 


Examples | 

This example sends two MLM_QUERYSEL messages to obtain the beginning and ending 
points of the current selection, sends an MLM_SETIMPORTEXPORT message to set up the 
export buffer, and then sends an MLM_EXPORT message to export the selection into the 
buffer. 
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MLM_QUERYSELTEXT 


This message copies the currently selected text into a buffer. 


Parameters 
param1 


pchBuff (PCHAR) 
Character buffer for text string. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulCount (ULONG) 
Number of bytes to put into text string. 


Remarks 

This message copies the currently selected text into the buffer pointed to by pchBuff. The 
text string is null-terminated. The byte count includes the text in CF_TEXT format (CR LF) 
and the null terminator. 


Default Processing 
The default window procedure takes no action on this message, other than to set ulCount to 
0. 


MLM_QUERYTABSTOP 


This message queries the pel interval at which tab stops are placed. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
pixTabset (PIX) 
Tab width in pels. 


<Q An error occurred. 
Other The pel interval at which tab stops are placed. 


Remarks 
This message fails and returns a negative value, if the reserved values are not 0. 


Default Processing 
The default window procedure takes no action on this message, other than to set pixTabset 
to 0. 


MLM_QUERYTEXTCOLOR 


This message queries the text color. 


- Parameters 
- param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
- Reserved value, should be 0. 


Returns 
IColor (LONG) 
Text color. 


Remarks 
This message returns the color in which text is to be drawn. 


The color values are the same as those used by GpiSetColor. 


Default Processing 
The default window procedure takes no action on this message, other than to set /Color to 0. 


16-30 PM Programming Reference Vol Il 


MLM_QUERYTEXTLENGTH 


This message returns the number of characters in the text. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
iptText (IPT) 
Count of text in bytes. 


Remarks 
This message returns the number of characters in the text. Hard line-breaks are counted as 
1 and soft line-breaks as 0. 


This message differs from the WinQueryWindowTextLength call in that it returns a LONG. 


Default Processing | 
The default window procedure takes no action on this message, other than to set jptText to 
0. ; 


MLM_QUERYTEXTLIMIT 


This message queries the maximum number of bytes that a multi-line entry field control can 
contain. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ISize (LONG) 
Maximum number of bytes allowed in the MLE. 


Remarks 

The multi-line entry field control window procedure responds to this message by returning the 
current limit set, either by default, or by MLM_SETTEXTLIMIT. If the limit is unbounded, a 
non-positive value is returned. 


Default Processing 
The default window procedure takes no action on this message, other than to set /Size to 0. 


MLM_QUERYUNDO 


This message queries the undo or redo operations that are possible. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


usOperation (USHORT) 
Operation that can be undone or redone. 


0 An undo or redo operation is not possible. 

WM_CHAR A WM_CHAR message, or messages for a simple string 
. -_ of keystrokes, can be undone or redone. 

MLM_SETFONT A MLM_SETFONT message can be undone or redone. 


MLM_SETTEXTCOLOR A MLM_SETTEXTCOLOR message can be undone or 
redone for both background and foreground color. 


MLM_CUT A MLM_CUT message can be undone or redone. 
MLM_PASTE A MLM_PASTE message can be undone or redone. 
MLM_CLEAR -  AMLM_CLEAR message can be undone or redone. 
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re (BOOL) 
Undo or redo indicator. 


TRUE  An.undo is possible. 
FALSE A redo is possible. 


Default Processing 
The default window procedure takes no action on this message, other than to set reply to 0. 


MLM_QUERYWRAP 


This message queries the wrap flag. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Wrap flag. 


TRUE Word-wrap enabled 
FALSE Word-wrap disabled. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_RESETUNDO 


This message resets the undo state to indicate that no undo operations are possible. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


usOperation (USHORT) 
Operation that can be undone or redone. 


0 An undo or redo operation is not possible. 

WM_CHAR A WM_CHAR message, or messages for a simple string 
of keystrokes, can be undone or redone. 

MLM_SETFONT A MLM_SETFONT message can be undone or redone. 


MLM_SETTEXTCOLOR AMLM_SETTEXTCOLOR message can be undone or 
redone for both background and foreground color. 


MLM_CUT A MLM_CUT message can be undone or redone. 


MLM_PASTE A MLM_PASTE message can be undone or redone. 
. MLM_CLEAR A MLM_CLEAR message can be undone or redone. 
re (BOOL) | . 


Undo or redo indicator. 


TRUE An undo is possible. 
FALSE A redo is possible. 


Remarks 

This message resets the undo state of the MLE to indicate that the last operation cannot be 
undone (null return from MLM_QUERYUNDO). This can be used by the application when it 
performs an operation that it can undo, that supersedes the last MLE operation. The 
application can then reset its own undo state upon receipt of an MLN_CHANGE, indicating 
that later changes have occurred through the MLE. 


Default Processing 
The default window procedure takes no action on this message, other than to set 
ReturnCode to 0. 
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MLM_SEARCH 


This message searches for a specified text string. 


Parameters 
param1 


ulStyle (ULONG) 
Style flags. 


MLFSEARCH_CASESENSITIVE __ If set, only exact matches are considered a 
successful match. If not set, any 
case-combination of the correct characters in 
the correct sequence is considered a successful 
match. 


MLFSEARCH_SELECTMATCH If set, the MLE selects the text and scrolls it into 
view when found, just as if the application had 
sent an MLM_SETSEL message. This is not 
done if MLFSEARCH_CHANGEALL is also 
indicated. 


MLFSEARCH_CHANGEALL Using the MLE_SEARCHDATA structure 
specified in pse, all occurrences of pchFind are 
found, searching from iptStart to iptStop, and 
replacing them with pchReplace. If this style is 
selected, the cchFound field has no meaning, 
and the iptStart value points to the place where 
the search stopped, or is the same as iptStop 
because the search has not been stopped at 
any of the found strings. The current cursor 
location is not moved. However, any existing 
selection is deselected. 


param2 


pse (PMLE_SEARCHDATA) 
Search specification structure. 


Returns 
re (BOOL) 
Success indicator. 


TRUE The search was successful. 
FALSE The search was unsuccessful. 
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Remarks 

This message searches the MLE text for a specified string, saning at a specified insertion 
point and continuing until the second specified insertion point has been reached, or the 
requested string has been matched. 


When an MLM_SEARCH message is sent, the text is scanned starting with the character 
that follows the insertion point indicated in the jptStart field of the MLE_SEARCHDATA 
structure. The search proceeds until the point indicated in the jptStop field, until a match is 
found, or until TRUE is returned from MLN_SEARCHPAUSE notification (see 
WM_CONTROL (in Multiline Entry Fields)). !f a negative value is specified for the jptStart, 
the current cursor point is used. If a negative value is specified for jptStop, the end of the 
text is used. If jotStop, is less than or equal to jptStart, after performing the two indicated 
substitutions, the search wraps from the end of the text to the beginning of the text. 


If the MLFSEARCH_CASESENSITIVE option is specified, the bytes of the search string must 
exactly match those in the text. If MLFSEARCH_CASESENSITIVE is not specified, the 
WinUpperChar of the search string must match the WinUpperChar of the text. 


When a match is found, the jptStart field of the search specification structure is set to 
indicate the insertion point immediately preceding the first character of the match, and the 
cchFind field is set to indicate the number of characters in the match. The cursor selection is 
not altered unless MLFSEARCH_SELECTMATCH is specified. If it is, am MLM_SETSEL is 
done with the anchor point at jptStart and the cursor at iptStart + cchFind. 


While searching, the MLE occasionally sends an MLN_SEARCHPAUSE notification 
message. If the owner responds to this message with the value TRUE, the MLE stops the 
search. When a search is stopped from MLN_SEARCHPAUSE, iptStart is set to the point 
where the search terminated. If the response is FALSE, the search continues (see also the 
definition of MLN_SEARCHPAUSE). The interval at which MLN_SEARCHPAUSE 
notifications are sent is implementation-dependent, but must not exceed reasonable 
user-response thresholds, nor should it be so often as to introduce undue messaging 
overhead. Sending this notification every half second is a reasonable compromise. 


When no match is found the jptStart value is unchanged. 
If the application needs to continue the search, the proper way is to change the /ptStart value 
to be the point following the string found, adjusting for any text changes done after the 


search that may have moved the relative location of the point. 


Applications using this message are advised to change the system pointer to the wait icon 
(clock face) if it is expected that the search will take some time. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 
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Examples 
This example searches for all occurrences of the word “Bonnie” and replaces them with the 
word “Jeannette.” 


MLE _SEARCHDATA search; 
search.cb = sizeof(search); 
search.pchFind = "bonnie"; 
search. pchReplace. = ."jeannette"; 


search.cchFind = 6; 

search.cchReplace.= 9; 

-search.iptStart = 0; /* from the beginning of the text */ 
search.iptStop = -1;  /* to the end of the text */ 
WinSendMsg(hwndMle, MLM SEARCH, MLFSEARCH_CHANGEALL, (MPARAM) &search) 


MLM_SETBACKCOLOR 


This message sets the background color. 


Parameters 
param1 


IColor (LONG) 
Color. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
lOldColor (LONG) 
Color previously used. 


Remarks 
This message sets the color in which the MLE background is to be drawn, and updates the 
display as necessary. 


The color values are the same as those used by GpiSetColor. 


Default Processing 
The default window procedure takes no action on this message, other than to set /OldColor 
to 0. 
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MLM_SETCHANGED 


This message sets or clears the changed flag. 


Parameters 
param1 


usChangedNew (USHORT) 
Value to set changed flag to. 


TRUE Changed flag set. 
FALSE Changed flag cleared. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Changed status before message was processed. 


TRUE — Text has changed since the last time that the change flag was cleared. 
FALSE Text has not changed since the last time that the change flag was cleared. 


Remarks 
This message can generate a MLN CHANGE notification. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_SETFIRSTCHAR 


This message sets the first visible character. 


Parameters 
param1 


iptFVC (IPT) 
Insertion point to place in top left-hand corner. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE An error occurred. 


Remarks 

This message scrolls the text to place the character following the insertion point into the 
upper left-hand corner of the window. If the insertion point specified is beyond the end of a 
line, or the end of the file, it is resolved in the same way as it is for a mouse click. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_SETFONT 


This message sets a font. 


Parameters 
param1 


pFattrs (PFATTRS) 
Font attribute structure. 


NULL The system font is set. 
other The specified font is set. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE _ The font was successfully set. 
FALSE An error occurred. 
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Remarks 
For any PFATTRS, this message sets the display to use the appropriate font. if NULL, the 
system font is used. The screen is updated appropriately. 


This can cause an overflow, see MLN_OVERFLOW. 


When setting an outline font it is necessary to ensure that the FATTRS structure contains the 
correct maximum baseline extent and average character width for the desired point size and 
that the font use is marked as FATTR_FONTUSE_TRANSFORMABLE. 


Baseline extent and character width are calculated by multiplying the desired point size by 
the current display device font resolution (CAPS_VERTICAL_FONT_RES and 
CAPS_HORIZONTAL_FONT_RES; see DevQueryCaps) and dividing by 72, the number of 
points in an inch. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Examples 
This example retrieves the current font information, changes it to italic, and sets it using the 
MLM_SETFONT message. 


MLM_SETFORMATRECT 


This message sets the format dimensions and mode. 


Parameters 
param1 


pFormatRect (PPOINTL) 
New format dimensions. 


NULL A null value sets both dimensions to the current window size. 


other The structure is a pair of LONGs designating the diagonally-opposite corner 
of the rectangle, assuming 0,0 for the first. Therefore, they are the width 
and height in pels of the format rectangle. These dimensions are used as 
the word-wrap and text-size limiting boundaries. Negative values for either 
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dimension cause the MLE to substitute the current window size (the MLE 
window rectangle minus margins). 


If the rectangle specified has either, or both, of the limits set, and the size is 
inadequate to contain the text, rc is set to FALSE and the rectangle 
dimensions are replaced with the overflow amounts. 


param2 


fiFlags (ULONG) 


Flags governing interpretation of dimensions. 


MLFFMTRECT_MATCHWINDOW 


MLFFMTRECT_LIMITHORZ 


MLFFMTRECT_LIMITVERT 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE _ An error occurred. 


Remarks 


The dimensions of the format rectangle are 
always to be kept the same as the window 
size minus the margins. This causes the MLE 
implicitly to do a MLM_SETFORMATRECT 
each time the window is resized, and 
effectively causes any other dimensions to be 
ignored. Resizing of the window can cause 
this setting to be automatically negated (see 
MLN_OVERFLOW). 


The width of any line in the MLE cannot 
exceed the given horizontal dimension. If 
word-wrap is on, this limit has no effect. 
Word-wrap can result in trailing blanks beyond 
the right limit. These do not cause an overflow 
notification. 


The vertical height of the total text, as 
displayed, is limited to that which fits totally 
within the vertical dimension of the format 
rectangle. 


The multi-line entry field control window procedure responds to this message by setting 


formatting dimensions and mode. 


Any addition of text that causes the text to exceed the rectangle limits causes a notification 
before proceeding (see MLN_PIXHORZOVERFLOW and MLN_PIXVERTOVERFLOW). 
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Any activity that would cause the rectangle to be unable to contain the existing text (resize, 
undo, increasing font size, or word-wrap on or off) is rejected and results in a notification 
message for information (see MLN_OVERFLOW). 


Default Processing 


The default window procedure takes no action on this message, other than to set rc to 
FALSE. . 
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MLM_SETREADONLY 


This message sets or clears read-only mode. 


Parameters 
_ param1 


usReadOnly (USHORT) 
New read-only value. 


TRUE Read-only mode set. 
FALSE Read-only mode cleared. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Previous read-only value. 


TRUE Read-only mode was set. 
FALSE Read-only mode was cleared. 


Remarks 

When read-only mode is set, characters typed at the keyboard do not get inserted into the 
MLE text. The API insertion interface, however, is still functional, as are 
selection-manipulation activities and copy-to-clipboard operations. This is useful as a means 
of preventing text modification (such as in a help system), and for providing a minimal 
blocking printing semaphore. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_SETIMPORTEXPORT 


This message sets the current transfer buffer. 


Parameters 
param1 


pBuff (PCHAR) 
Transfer buffer. 
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param2 


ulLength (ULONG) 
Size of transfer buffer in bytes. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE An error occurred. 


Remarks 

Given a far pointer to a buffer, and the size of the buffer, this message sets it as the current 
transfer buffer for the MLE. This buffer is used by the MLM_IMPORT and MLM_EXPORT 
messages. The system segment limit must be observed when specifying the buffer size. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 
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MLM_SETSEL 


This message sets a selection. 


Parameters 
param1 


iptAnchor (IPT) 
Insertion point for new anchor point. 


param2 


iptCursor (IPT) 
Insertion point for new cursor point. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Selection successfully set 
FALSE An error occurred. 


Remarks 

This message sets the anchor and cursor points. The screen display is updated 
appropriately, ensuring that the cursor point is visible (which may involve scrolling). Note 
that the text cursor and inversion are not displayed if the MLE window does not have the 
input focus. A negative value for a point leaves that point alone. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Examples 
This example highlights the second, third, and fourth characters of the text, and places the 
cursor to the right of the fourth character. 


“WinSendMsg(hwndMie, MLM SETSEL, (MPARAM) 1L, (PARAM) 4L); 
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rs 


MLM_SETTABSTOP 


This message sets the pel interval at which tab stops are placed. 


Parameters 
param1 


pixTab (PIX) 
Pel interval for tab stops. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
pixTabset (PIX) 
Success indicator. 


<Q An error occurred. 
Other The value to which the width was set. 


Remarks 
This message fails if the reserved value is not 0. 


This message can cause an overflow, see MLN_OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set pixTabset 
to 0. 


MLM_SETTEXTCOLOR 


This message sets the text color. 


Parameters 
param1 


IColor (LONG) 
Color. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
lOldColor (LONG) 
Color previously used. 


Remarks 
This message sets the color in which the MLE text is to be drawn, and updates the display 
as necessary. 


The color values are the same as those used by GpiSetColor. 


Default Processing 
The default window procedure takes no action on this message, other than to set /O/dColor 
to 0. 


MLM_SETTEXTLIMIT 
This message sets the maximum number of bytes that a multi-line entry field control can 
contain. 


Parameters 
param1 


ISize (LONG) 
Maximum number of characters in MLFIE_NOTRANS format. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulFit (ULONG) 
Success indicator. 


0 Successful completion. Current text fits within the new limit. 
Other The number of bytes by which the current text exceeds the proposed limit. The 
limit is not changed. 
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Remarks | | . 

The multi-line entry field control window procedure responds to this message by limiting the 
text size to /Size bytes. Text size is calculated using the MLFIE_NOTRANS format. Note 
that this is bytes and not characters; DBCS programmers should calculate accordingly. 


This message returns 0 if the text limit exceeds or is equal to the existing text. Otherwise it 
returns the number of bytes by which the text would have overflowed, and does not change 
the limit. 


The default, which is unbounded, can be specified by entering a non-positive limit. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Fit to 0. 


MLM_SETWRAP 


This message sets the wrap flag. 


Parameters 
param1 


usWrap (USHORT) 
New value for wrap flag. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE An error occurred. 


Remarks 
The multi-line entry field control window procedure responds to this message by setting the 
word wrap mode and updating the screen as appropriate. 


When word-wrap is turned on, the text is wrapped to fit the formatting saendis width. When 
word-wrap is turned off, the text is allowed to trail off to the ant until it reaches an 
end-of-line marker. 


Word-wrapping is defined as follows. Words are sequences of non-white-space. characters 
(white-space characters are space, line break, and tab). When word-wrapping is enabled, 
the whole word must appear on one line within the formatting rectangle, unless the word by 
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itself is too long to fit. In this case the word is split following the last character that fits, and 
the remainder starts a new line. 


This definition then applies recursively to the remainder of the word. The word continues to 
be visible. For editing purposes (for example, for word-selection) the word is viewed as a 
single word drawn over multiple lines. 


Blank characters are always accumulated onto the current line, even if they exceed the 
horizontal formatting dimension, that is, blanks are allowed to trail off the right-hand edge. 
Line-break characters are also allowed to exceed the horizontal dimension, and any 
subsequent text must begin on a new line. The line-break following a line-break character is 
sometimes referred to as a hard line-break. Other line breaks, due to word-wrapping, and 
not to explicit formatting characters, are referred to as soft line-breaks. 


Tab characters must always be visible. If a tab character occurs after the last tab stop within 
the horizontal formatting dimension, a soft line-break occurs after the tab. 


This message can cause an overflow, see MLN_OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


MLM_UNDO 


This message performs any available undo operation. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (USHORT) 
Success indicator. 


TRUE An undo operation was performed. 
FALSE No undo operation was performed. 
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Remarks 
The last operation is undone (note that an undo can be undone). 


This can cause an overflow, see MLN_ OVERFLOW. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


WM_BUTTON1DBLCLK (in Multiline Entry Fields) 
For the cause of this message, see “WM_BUTTON1DBLCLKk” on page 10-12. 


For a description of the parameters, see “WM_BUTTON1DBLCLK’” on page 10-12. 


Remarks 
This message indicates that mouse button 1 has clicked twice within the system double-click 
time. 


Double-Click © 

If the click point is in the middle of a non-white-space character, the token (word) 

surrounding the clicked-on character, and any trailing spaces, are selected. If the click point 

is in a space character, the previous word (along with the trailing spaces including the 

clicked-on space) is selected. If there is no preceding word (either because the spaces are 

at the beginning of the text or immediately follow a line-break character) the run of spaces is 
selected. if the click point is on a tab or line-break character, that character is selected. 


Shift- Double- Click 

Double-clicking while the Shift key is pressed leaves the anchor point alone, and moves the 
cursor point to the beginning or end of the clicked-on token. If the click point is before the 
anchor point in the text, the cursor point is moved to the beginning of the surrounding word, 
otherwise, the cursor point is moved to the end of the surrounding word. When 
shift-double-clicking, the selection is extended to include the token that was double-clicked 
on. . 


Margin Mouse Event 

All mouse events in a margin cause the MLE to send a MLN_MARGIN notification to the 
owner window of the MLE. This message has, as its parameters, the original mouse | 
message. The owner can process the notification or not. If the owner does not process the 
message, the event is treated as if it occurred on the closest point in the text. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_BUTTON1DBLCLK 
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WM_BUTTON1DOWN (in Multiline Entry Fields) 
For the cause of this message, see “WM_BUTTON1DOWN’” on page 10-13. 


For a description of the parameters, see “WM_BUTTON1DOWN” on page 10-13. 


Remarks 

This message delimits mouse button click events. Between a button-down and a button-up 
event, the mouse is considered to be dragging. A mouse click is considered to happen on 
button-down, and dragging is terminated by a button-up. 


Click 

Clicking in the text sets the cursor and anchor points to the nearest insertion point. If the 
MLE is in overtype mode, the anchor is extended one character further in the text, subject to 
the end-of-text and new-line boundary conditions, defined under WM_CHAR (in Multiline 
Entry Fields). 


Shift-Click 
Clicking while the shift key is held down sets the cursor point to the nearest insertion point, 
while leaving the anchor point alone. 


Margin Mouse Event 

All mouse events in a margin cause the MLE to send a MLN_MARGIN notification to the 
owner window of the MLE. This message has, as its parameters, the original mouse 
message. The owner can process the notification or not. If the owner does not process the 
message, the event is treated as if it occurred on the closest point in the text. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
* WM_BUTTON1IDOWN 


WM_BUTTON1UP (in Multiline Entry Fields) 
For the cause of this message, see “WM_BUTTON1UP” on page 10-16. 


For a description of the parameters, see “WM_BUTTON1UP” on page 10-16. 


Remarks 

This message delimits mouse button click events. Between a button-down and a button-up 
event the mouse is considered to be dragging. A mouse click is considered to happen on 
button-down, and dragging is terminated by a button-up. 


Margin Mouse Event 

All mouse events in a margin cause the MLE to send a MLN_MARGIN notification to the 
owner window of the MLE. This message has, as its parameters, the original mouse 
message. The owner can process the notification or not. If the owner does not process the 
message, the event is treated as if it occurred on the closest point in the text. 
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Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
_ FALSE. 


Related Messages 
¢ WM_BUTTON1UP 


WM_CHAR (in Multiline Entry Fields) 
For the cause of this message, see “WM_CHAR” on page 10-32. 


For a description of the parameters, see “WM_CHAR’” on page 10-32. 


Remarks 

The behavior of the MLE, when typing, depends on whether it is in insert or overtype mode, 
and whether the selection is empty or not. The selection is defined to be empty when the 
cursor point is equal to the anchor point. 


When a character is typed, it replaces the current selection. If the selection is empty, the 
character is viewed as replacing nothing, so the character is effectively inserted into the text. 
If one or more characters are selected, those characters are deleted from the text and 
replaced by the typed character. 


If the MLE is in insert mode, the cursor and anchor points are moved to immediately follow 
the newly typed character. 


If the MLE is in overtype mode, the cursor is moved to immediately follow the newly typed 
character. If there is no character after the cursor (the new character is at the end of the 
text) or if the character after the cursor is a line-break character, the anchor is set to be 
equal to the cursor point. In any other case, the anchor is extended one character past the 
cursor point, defining the next character as the current selection. 


If the typing causes the cursor to go off the screen in any direction, the display is 
automatically scrolled. If word-wrap is on, text continues on a new line, otherwise, the 
screen is scrolled horizontally. . 


Scrolling of the text in the window is independent of cursor movement. The cursor and 
selection remain unaltered at the same location within the text during all scrolling but the 
converse is not true. Any movement of the cursor causes auto-scrolling, if necessary, to 
ensure that the text location of the cursor is visible within the window. 


Tabs: Tabs are represented as a single character in the text model, and are displayed as 
enough white-space to reach the next tab stop. Tab stops are set at pel intervals, starting 
with zero and occurring every n pels, where n is a value set by the MLM_SETTABSTOP 
message, and defaulting to eight times the average character width of the system font. 
When a tab is drawn, it uses the number of pels defined by the following formula: 


pelWidth = pelTab - (pelDraw mod pelTab)) 
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- where pelTab is the tab interval, in pels, and pelDraw is the pel at which drawing is to begin. 


Return: Return (ASCII newline) causes a hard line-break, and the following text begins on 
a new line. A line-break character is inserted in the text, which is drawn as a few pels of 
white-space (for selection purposes). 


Keystroke commands: For all the following keys, unless otherwise noted, the display is 
scrolled, if necessary, to keep the cursor point visible. Where noted, the cursor setting 
behaves differently in insert mode than in overtype mode. This is subject to the boundary 


conditions noted above. 


Del 


Shift+Del 
Insert 
Shift+Ins 
Ctrl+iIns 


Backspace 


Down Arrow 


Shift+Down Arrow 


Up Arrow 


Shift+Up 


Causes the contents of the selection region to be deleted. If 
the selection region contains no text, it causes the character 
to the right of the cursor to be deleted. 


Causes the contents of the selection region to be cut to the 
clipboard. 


Toggles between insert and overtype mode. The MLE 
ignores the Insert key when it occurs without a modifier. 


Causes the contents of the clipboard to replace the selection 
region. 


Causes the selection region to be copied to the clipboard. 
The selection region is not otherwise affected. 


Functions similar to Del. If the selection is not empty, 
Backspace deletes the selection. If the selection is empty, 
Backspace deletes the character to the left of the cursor point. 
If the MLE is in overtype mode, the anchor point is set, and 
the cursor point is moved to be one character previous in the 
text. If no such character exists (because the anchor is set to 
the beginning of the text) the cursor is set to the anchor point. 
If the MLE is in insert mode, the cursor and anchor points are 
set, as defined at the start of this chapter. 


Sets the cursor point to the closest insertion point on the 
following line, then sets the anchor point to the cursor point 
(insertion mode) or one character following (overtype mode). 


Causes the cursor point to be moved to the closest insertion 
point on the following line. The anchor point does not move. 


Sets the cursor point to the closest insertion point on the 
preceding line, then sets the anchor point to the cursor point 
(insert mode) or one character following (overtype mode). 


Sets the cursor point to the closest insertion point on the 
preceding line. The anchor point is not moved. 
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Right Arrow 


Shift+Right 


Left and Shift+Left 
Ctrl+Right 


Ctrl+Shift+Right 


Ctrl+Left 


Ctrl+Shift+Left 


Pagedown and Pageup 


Sets the cursor point to the insertion point one character 
following the cursor point. The anchor point is set to the 
cursor point (insert mode) or one character following (overtype 
mode). 


Causes the cursor point to be set to the insertion point 
immediately following the previous cursor point. The anchor 
point is not moved. 


Work analogously. 


Moves the cursor point to the insertion point immediately 
preceding the next word in the text including trailing spaces, 
and sets the anchor point to be equal to (insert mode) or one 
character following (overtype mode) the cursor point. The 
EOL (hard line-break) and tab characters are treated as 
words. 


Moves only the cursor point in the same way as Ctrl+Right, 


but leaves the anchor point unmoved. 


Moves the cursor point to the preceding insertion point at the 
beginning of a word, and sets the anchor point to be equal to 
(insert mode) or one character following (overtype mode) the 
cursor point. The EOL (hard line-break) and tab characters 
are treated as words. | 


Moves only the cursor point in the same way as Cirl+Left but 
leaves the anchor point unmoved. 


Cause the display to be scrolled one screen at a time in either 
direction. This behavior is the same as would be encountered 
during a page-down or page-up caused by the scroll-bar. 


Ctrl+Pagedown and Ctrl+Pageup Cause the display to be scrolled one screen at a time to 


Home 


Shift+Home 


End 


the right or left respectively. This behavior is the same as 
would be encountered during a page-right or page-left caused 
by the scroll-bar. 


Sets the cursor point to the insertion point at the beginning of 
the line containing the cursor point, and sets the anchor point 
equal to (insert mode) or one character following (overtype 
mode). 


Moves the cursor point to the insertion point at the beginning 
of the line. The anchor point is not moved. 


Sets the anchor point to the insertion point at the end of the 
line containing the cursor point. If the last character on the 
line is a line-break character, the anchor is positioned just 
before it. The cursor is set equal to (insert mode) or one 
character previous to (overtype mode) the anchor. 


16-54 PM Programming Reference Vol II 


Shift+End Moves the cursor point to the insertion point at the end of the 
line, as above. The anchor point is not moved. 


Ctri+Home Moves the cursor point to the insertion point at the beginning 
of the document. The anchor point is set equal to (insert 
mode) or one character following it (overtype mode). 


Ctrl+End Moves the anchor point to the insertion point at the end of the 
document. The cursor point is set to be equal to the anchor 
point (insert mode) or one character preceding it (overtype 
mode). 


Ctrl+Shift+Home Moves the cursor point in the same way as Ctrl+Home, but 
leaves the anchor point unmoved. 


Ctrl+Shift+End Moves the cursor point in the same way as Ctrl+End, but 
leaves the anchor point unmoved. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_CHAR 


WM_ENABLE (in Multiline Entry Fields) 
For the cause of this message, see “WM_ENABLE” on page 10-43. 


For a description of the parameters, see “WM_ENABLE” on page 10-43. 


Remarks 
The multi-line entry field control window procedure responds to this message by setting the 
enable state and by setting u/Reserved to 0. 


Disabling the window is similar, but not identical, to MLM _DISABLEREFRESH. Enabling the 
window is similar, but not identical, to MLM_ENABLEREFRESH. (Note that this also applies 
to window styles.) The difference is that a disabled window receives no mouse or keyboard 
input whereas with MLM_DISABLEREFRESH it receives the input but discards it. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_ENABLE 
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WM_MOUSEMOVE (in Mulitline Entry Fields) 
For the cause of this message, see “WM_MOUSEMOVE” on page 10-59. 


For a description of the parameters, see “WM _MOUSEMOVE?” on page 10-59. 


Remarks 

The mouse pointer moves and is of interest to the MLE. If refresh is disabled, the pointer is 
set to the wait icon (a clock face). If refresh is enabled, the pointer is set to an !-beam. This 
message can occur during dragging or when simply tracking the mouse. 


Dragging Dragging sets the selection anchor to be the point where dragging 
begins, and moves the cursor point along with it as the mouse is 
moved. Moving the pointer into the margins while dragging 
produces a scroll in the appropriate direction and continues 
selecting. 


Margin Mouse Event _ All mouse events in a margin cause the MLE to send a 
MLN_MARGIN notification to the owner window MLE. This 
message has, as its parameters, the original mouse message. The 
owner can process the notification or not. If the owner does not 
process the message, the event is treated as if it occurred on the 
closest point in the text. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 0 
(FALSE). 


Related Messages 
¢ WM _MOUSEMOVE 


WM_QUERYWINDOWPARAMS (in Multiline Entry Fields) 


This message occurs when an application queries the entry field control window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?” on page 10-75. 


Remarks 

The multi-line entry field control window procedure responds to this message by returning the 
window parameters indicated by the fsStatus parameter of the WNDPARAMS data structure, 
identified by the pwndparams parameter. 


In response to the WPM_CCHTEXT flag, the text length is reported in the CF_TEXT format. 
If it exceeds 64KB-1, then this value is reported. In response to the WPM_TEXT flag, text 

up to the amount returned for the WPM_CCHTEXT value is placed at the indicated location 
in CF_TEXT format. 
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Default Processing 
The default window procedure sets the cchText, cbPresParams, and cbCtlData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to 0 and sets rc to FALSE. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 


WM_SETWINDOWPARAMS (in Multiline Entry Fields) 


This message occurs when an application sets or changes the entry field control window 
parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS?” on page 10-86. 


Remarks 

The multi-line entry field control window procedure responds to this message by setting the 
window parameters indicated by the fsStatus parameter of the WNDPARAMS data structure, 
identified by the pwndparams parameter. 


if the MLE text is to be set by this message, it is assumed to be in CF_TEXT format (see 
MLM_FORMAT) and all existing text is deleted before the new text is inserted. Note that a 
Control Data structure can be associated with the window parameters, in which case any 
field in that structure can cause a change to the MLE. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_SETWINDOWPARAMS 
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Chapter 17. Combination-Box Control Window Processing 


This system-provided window procedure processes the actions on a prompted entry field 
(combination-box) control (WC_COMBOBOX). 


Purpose 
A combination-box consists of an entry field control and a list box control merged into a 
single control. The list, which is usually limited in size, is displayed below the entry field, and 
offset one dialog-box unit to its right. 


When the combination-box control has the focus, the text in the entry field is given selected 
emphasis and, if the list box control has a matching entry, it is scrolled to show that match at 
the top of the list. 


A combination-box, while sometimes only showing the entryfield, also owns the area 
occupied by the invisible list box. Another window can and will be clipped to it if they have 
clipping flags set. . 


Combination Box Control Styles 
These combination-box control styles are available: 


CBS_SIMPLE Both the entry field control and the list box control are visible. 
When the selection changes in the list box control, the text of 
the selected item in the list box control is placed in the entry 
field. Also, the text in the entry field is completed by extending 
the text of the entry field with the closest match from the list 
box. 


CBS_DROPDOWN Inherits all the properties of a combination-box control with a 
style of CBS_SIMPLE and, in addition, the list box control is . 
hidden until the user requests that it should be displayed. 


CBS_DROPDOWNLIST In which the entry field control is replaced by a static control, 
that displays the current selection from the list box control. The 
user must explicitly cause the display of the list box control in 
order to make alternative selections in the list box. 


Combination Box Control Data 
None. 
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Default Colors 
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The following system colors are used when the system draws button controls: 


SYSCLR_WINDOWFRAME 
SYSCLR_ENTRYFIELD 
SYSCLR_WINDOW 
SYSCLR_BUTTONMIDDLE 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONLIGHT 
SYSCLR_OUTPUTTEXT 
SYSCLR_WINDOWTEXT 
SYSCLR_HIGHLITEFOREGROUND 
SYSCLR_HIGHLITEBACKGROUND 
SYSCLR_FIELDBACKRGOUND 
SYSCLR_WINDOWFRAME. 


Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_FOREGROUNDCOLOR 
PP_DISABLEDFOREGROUNDCOLOR 
PP_HIGHLIGHTFOREGROUNDCOLOR 
PP_FONTNAMESIZE 
PP_BORDERCOLOR. 
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Combo Box Control Notification Messages 


The combo box control uses most of the same window messages as the entry field control 
and the list box control to notify its owner of significant events. 


WM_CONTROL (in Combination Boxes) 
For the cause of this message, see “WM CONTROL’ on page 10-39. 


Parameters 
param1 


usid (USHORT) 
Control window identity. 


usnotifycode (USHORT) 
Notify code. 


CBN_EFCHANGE __ The content of the entry field control has changed, and the 
change has been displayed on the screen. 


CBN_MEMERROR The entry field control cannot allocate the storage necessary 
to accommodate window text of the length implied by the 
EM _SETTEXTLIMIT message. 


CBN_EFSCROLL _ The entry field control is about to scroll horizontally. This can 
happen in these circumstances: 


¢ The application has issued a WinScrollWindow call. 
e The content of the entry field contro! has changed. 
¢ The caret has moved. 


The entry field control must scroll to show the caret position. 
CBN_LBSELECT An item in the list box control has been selected. 
CBN_LBSCROLL _ The list box is about to scroll. 
CBN_SHOWLIST _ The list box is about to be displayed. 


CBN_ENTER The user has depressed the ENTER key or double clicked 
(single clicked in the case of a drop-down list) on an item in 
the list box control. 


param2 


hwndcontrolspec (HWND) 
Combination (combo) window handle. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks. 
The entry field control window procedure generates this message and sends it to its owner, 
informing the owner of the event. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 


to 0. 


Related Messages 
e WM_ CONTROL 
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Combo Box Control Window Messages 


The combo box control uses most of the same messages as the entry field control and the 
list box control. In particular, the following messages are supported to achieve the functions 
of a combo box. These messages are explained in detail in the entry field control window 
messages and the list box control window messages sections. 


WM_SETWINDOWPARAMS (in Entry Fields) To set the text of the entry field. 
WM_QUERYWINDOWPARAMS (in Entry Fields) To obtain the text of the entry field. 


LM_QUERYITEMCOUNT 
LM_INSERTITEM 
LM_SETTOPINDEX 


LM_QUERYTOPINDEX 


LM_DELETEITEM 


LM_SELECTITEM 


LM_QUERYSELECTION 
LM_SETITEMTEXT 


LM_QUERYITEMTEXT 
LM_QUERYITEMTEXTLENGTH 
LM_SEARCHSTRING 


LM_DELETEALL 
WM_ENABLE 
EM_QUERYFIRSTCHAR 


EM_SETFIRSTCHAR 


EM_QUERYCHANGED 
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To obtain the count of items in the list box control. 
To insert an item into the list box control. 


To scroll the list box control so that the specified item is 
at the top. 


To obtain the index of the item at the top of the list box 
control. 


To delete an item from the list box control. If 
necessary, this also changes the content of the entry 
field to the item at the top of the list box control. 


To select a specified item in the list box control. Also, 
this changes the content of the entry field to the item at 
the top of the list box control and, if the list box control 
is not visible, causes the list box control to ‘dropdown’ 
below the entry field control. 


To obtain the current selection in the list box control. 


To change the text of an item in the list box control. If 
necessary, this also changes the content of the entry 
field control. 


To obtain the text of an item in the list box control. 


To obtain the length of the text of an item in the list box 
control. 


To obtain the index of an item in the list box control 
containing a specified string. 


To delete all the items in the list box control. 
To enable the combo box control to respond to input. 


To obtain the character displayed at the left edge of the 
entry field control. 


-To scroll the entry field control so that the specified 


character is displayed at the left edge of the entry field 
control. 


To obtain the changes to the entry field control. 


17-5 


EM_QUERYSEL To obtain the current selection of the entry field control. 
EM_SETSEL To set the current selection of the entry field control. 


EM_SETTEXTLIMIT To set the maximum number of characters to be 
contained in the entry field control. 


EM_CUT To place the contents of the selection of the entry field 
. control into the clipboard and then delete those contents 
from the entry field control. 


EM_PASTE To place the contents of the clipboard into the entry 
field control. 
EM_COPY To place the contents of the selection of the entry field 


control into. the clipboard. 
EM_CLEAR To clear the current selection of the entry field control. 


This section describes the combo box control window procedure actions on receiving these 
messages: > 


CBM_HILITE 


This message sets the highlighting state of the entry field control. 


Parameters 
param1 


usHilite (UVSHORT) 
Highlighting indicator. 


TRUE Highlight the entry field control. 
FALSE Do not highlight the entry field control. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Changed indicator. 


TRUE _ The highlighting state of the entry field has been changed. 
FALSE _ The highlighting state of the entry field has not been changed. 


Remarks 7 
The combo box control window procedure responds to this message by setting the 
highlighting state of the entry field control. 
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Default Processing 
WinDefWindowProc does not expect to receive this message and therefore takes no action 
on it, other than to set rc to the default value of FALSE. 


CBM_ISLISTSHOWING 


This message determines if the list box control is showing. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Showing indicator. 


TRUE _ The list box control is showing. 
FALSE _ The list box control is not showing. 


Remarks 
The combo box control window procedure responds to this message by indicating if the list 
box control is showing. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


CBM_SHOWLIST 


This message sets the showing state of the list box control. 


Parameters 
param1 


usShowing (USHORT) 
Showing indicator. 


TRUE Show the list box control. 
FALSE Do not show the list box control. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Changed indicator. 


TRUE _ The list box showing state has been changed. 
FALSE _ The list box showing state has not been changed. 


Remarks 
The combo box control window procedure responds to this message by setting the showing 
state of the list box control. 


This message has no effect on a combo box control whose style is CBS_SIMPLE. 


Hiding the list box control has no effect on the selection in the list box control. The selection 
in the list box control must be changed by the use of a LM_SELECTITEM message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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Chapter 18. Scroll Bar Control Window Processing 


This system-provided window procedure processes the actions on a scroll bar control 
(WC_SCROLLBAR). 


Purpose 
Scroll bars are controls used to indicate that additional information can be displayed in a 
window, logically to the left or right for horizontal scroll bars, logically above or below for 
vertical scroll bars. The user interface for scroll bars allows for scrolling one unit or one 
page at a time, or alternatively picking up the scroll bar slider and moving it to a position in 
the scroll bar that indicates a logical position in the data. 


Scroll Bar Control Styles 


These scroll bar control styles are available: 


SBS_HORZ Create a horizontal scroll bar. 

SBS_VERT Create a vertical scroll bar. 

SBS_THUMBSIZE Indicates the presence of the cVisible and cTota/ parameters in the 
SBCDATA data structure. 

SBS_AUTOTRACK _ The slider scrolls as more information is being displayed on the 
screen. 


SBS_AUTOSIZE The scroll bar slider changes size to reflect the amount of data 
contained in the window. 


Scroll Bar Control Data 
See “SBCDATA’” on page A-182. 


Default Colors 
The following system colors are used when the system draws button controls: 


SYSCLR_SCROLLBAR 
SYSCLR_WINDOWFRAME 
SYSCLR_FIELDBACKGROUND 
SYSCLR_WINDOW 
SYSCLR_BUTTONMIDDLE. 
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Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_FOREGROUNDCOLOR 
PP_BORDERCOLOR 
PP_ HILITEFOREGROUNDCOLOR. 


Scroll Bar System Values 
Applications can use the following system values to create and add control scroll bars: 
SV_CXVSCROLL Width of the vertical scrolli-bar. 
SV_CYHSCROLL Height of the horizontal scroll-bar. 
SV_CYVSCROLLARROW _ Height of the vertical scroll-bar arrow bit maps. 
~ SV_CXHSCROLLARROW _ Height of the vertical scroil-bar arrow bit maps. 


SV_FIRSTSCROLLRATE _ The delay (in milliseconds) before autoscrolling starts, when 
using a scroll bar. 


SV_SCROLLRATE The delay (in milliseconds) between scroll operations, when 
using a scroll bar. 


SYSCLR_SCROLLBAR Color for drawing scroll-bar backgrounds. 


TID_SCROLL Timer ID for a reserved scrolling time. This is used for sending 
notification messages when a scroll-arrow or scroll-bar 
background is selected. 
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Scroll Bar Control Notification Messages 


These messages are initiated by the scroll bar control window procedure to notify its owner 
of significant events. 


WM_HSCROLL (in Horizontal Scroll Bars) 
For the cause of this message, see “WWM_HSCROLL” on page 10-51. 


For a description of the parameters, see “WM_HSCROLL” on page 10-51. 


Remarks 
The scroll bar control window procedure generates this message and posts it to its owner, 
informing the owner of the event. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
¢ WM_HSCROLL 


WM_VSCROLL (in Vertical Scroll Bars) 
For the cause of this message, see “WM_VSCROLL” on page 10-99. 


For a description of the parameters, see “WM_VSCROLL” on page 10-99. 


Remarks 
The scroll bar control window procedure generates this message and posts the message to 
the owner of the procedure, informing the owner of the event. 


Default Processing 
The default window procedure takes no action on this message, other than to set ul/[Reserved 


to 0. 


Related Messages 
¢ WM_VSCROLL 
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Scroll Bar Control Window Messages 


This section describes the scroll bar control window procedure actions on receiving the 
following messages. 


SBM_QUERYPOS 


This message returns the current slider position in a scroll bar window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
sslider (SHORT) 
Slider position. 


Remarks | 
The scroll bar control window procedure responds to this message by returning the current 
slider position. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set ss/ider to the default value of 0. 


SBM_QUERYRANGE 


This message returns the scroll bar range minimum and maximum values. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


sfirst (SHORT) 
First bound. 


slast (SHORT) 
Last bound. 


Remarks 
The scroll bar control window procedure responds to this message by returning the first and 
last bounds of the scroll bar range. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set ReturnCode to the default value of sfirst and siast to 0. 


SBM_SETPOS 


This message sets the position of the slider in a scroll bar window. 


Parameters 
param1 


sslider (SHORT) 
Position of slider. 


If this value is outside the scroll-bar range, the slider is moved to the nearest valid 
position within the range. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred 


Remarks 
The scroll bar control window procedure responds to this message by setting the position of 
the slider. 


The scroll bar control is redrawn to reflect the change. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 


no action on it. 


SBM_SETSCROLLBAR 


This message sets the scroll-bar range and slider position. 


Parameters 
param1 


sslider (SHORT) 
Position of slider. 


If this value is outside the scroll-bar range, the slider is moved to the nearest valid 
position within the range. . 


param2 


sfirst (SHORT) 
First bound. 


This value must not be less than 0. If a value less than 0 is supplied, 0 is used as . 
the value. 

slast (SHORT) 
Last bound. 


The value must not be less than 0 or sfirst. |f a value less than this is supplied, the 
higher of 0 or sfirst is used as the value. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The scroll bar control window procedure responds to this message by setting the values of 
the information range and the position of the slider. 


The scroll bar is redrawn to reflect the change. 


For example, if a scroll-bar is to allow scrolling through 100 lines of text, of which 50 are 
visible at any one time, and the top display line is currently number 25, sfirst should be set to 
1, slast to 51 (since there are only 51 positions at which the slider may be placed), and 
sslider to 25. The SBM_SETTHUMBSIZE message should be used in this example to set 
the slider size to 50 visible parts out of 100. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it. 


SBM_SETTHUMBSIZE 


This message sets the scroll bar slider size. 


Parameters 
param1 


svisible (SHORT) 
Size of the visible part of the document. 


stotal (SHORT) 
Size of the entire document. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Chapter 18. Scroll Bar Control Window Processing 18-7 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 

The scroll bar control window procedure responds to this message by setting the size of the 
slider proportional to the visible part of the document. If the visible part exceeds or is equal 
to the entire document the scroll bar is disabled, otherwise the scroll bar is enabled. 


The scroll bar is redrawn to reflect the change. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it. 


WM_QUERYCONVERTPOS (in Scroll Bars) 
For the cause of this message, see “WM_QUERYCONVERTPOS?’ on page 10-72. 


For a description of the parameters, see “WM_QUERYCONVERTPOS’ on page 10-72. 


Remarks 
The scroll bar control window procedure returns QCP_NOCONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS’ on page 10-72. 


Related Messages 
¢ WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in Scroll Bars) 
This message occurs when an application queries the scroll bar control window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMSG’ on page 10-75. 
Remarks 
The scroll bar control window procedure responds to this message by returning the window 


parameters indicated by the fsStatus parameter of the WNDPARAMS data structure 
identified by the pwndparams parameter. 


Default Processing 
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The default window procedure sets the cchText, cbPresParams, and cbCtiData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to 0 and sets rc to FALSE. 


Related Messages 
e WM_QUERYWINDOWPARAMS 


WM_SETWINDOWPARAWMS (in Scroll Bars) 


This message occurs when an application sets or changes the scroll bar control window 
parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS?’ on page 10-86. 


Remarks 

The scroll bar control window procedure responds to this message by setting the window 
parameters indicated by the fsStatus parameter of the WNDPARAMS data structure 
identified by the pwndparams parameter. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_SETWINDOWPARAMS 


NA 
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Chapter 19. Spin Button Control Window Processing 


This system-provided window procedure processes the actions on a spin button control 
(WC_SPINBUTTON). 


Purpose 


A spin button control (WC_SPINBUTTON window class) is a visual component whose 
specific purpose is to give users quick access to a finite set of data. The spin button allows 
users to select from a scrollable ring of choices. Since users can see only one item at a 
time, the spin button control should be used only with data that is intuitively related, such as 
a list of months of the year, or an alphabetic list of cities or states. 


A spin button consists of at least one spin field that is a single-line entry field (SLE), and up 
and down arrows that are stacked on top of one another. These arrows are positioned at the 
right of the SLE. 


You can create multifield spin buttons for those applications in which users must select more 
than one value. For example, in setting a date the spin button control can provide individual 
fields for setting the month, day, and year. The first spin field in the spin button could 
contain a list of months, the second spin field could contain a list of numbers and the third 
spin field could contain a list of years. 


Spin Button Control Styles 


Create a spin button using the style bits listed below. These styles can be joined together by 
using logical ORs (|). 


e Specify one of the following to determine whether a spin field will be a master or a 
servant. If neither is specified, SPBS_SERVANT is the default. 


SPBS_MASTER The spin button component consists of at least one single 
line entry field (SLE), or spin field, and two arrows, the Up. 
Arrow and the Down Arrow. When a spin button contains 
more than one spin field, the master component contains 
the spin arrows. If the component contains only one spin 
field, it should be a master. 


SPBS_SERVANT You can create a multifield spin button by spinning 
servants from the master. 


* Specify one of the following to determine the type of characters allowed in the spin field: 
SPBS_ALLCHARACTERS Any character can be typed in the spin field. This is the 


default. 

SPBS_NUMERICONLY Only the digits O—9 and the minus sign (—) can be typed in 
the spin field. 

SPBS_READONLY Nothing can be typed in the spin field. 
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Specify one of the following to determine how the text is to be presented in the spin 
field: j 


SPBS_JUSTLEFT Left-justify the text. This is the default. 


SPBS_JUSTRIGHT Right-justify the text. 

SPBS_JUSTCENTER Center the text. 

Specify the following when you do not want a border around the spin button: 
SPBS_NOBORDER Suppresses drawing a border. 

Specify the following to increase the spin speed: 

SPBS_FASTSPIN Enables the spin button to increase the spin speed with 


time. The speed doubles every two seconds. 


Note: The spin button skips information when this option is specified. Do not use 
SPBS_FASTSPIN if the application requires that this field be checked each time 
a spin up or spin down occurs. Do not specify this option on a master 
component that has servants spun from it. 


Specify the following to pad numeric fields with Os. This is useful when the spin field 
contains values that represent time or money. 


SPBS_PADWITHZEROS _ The output number is padded at the front between the first 
non-zero digit and the field width, or 11 characters, 
whichever is the lesser. The negative sign, if there is one, 
is retained. The maximum number of characters required 
to display a LONG number is 11. 


Spin Button Control Data 
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Spin Button Control Notification Message 


This message is initiated by the spin button control window to notify its owner of significant 
events. 


WM_CONTROL (in Spin Button Controls) 
For the cause of this message, see “WM_CONTROL’ on page 10-39. 


Parameters 
param1 


id (USHORT) 
Identity of the spin button component window. 


notifycode (USHORT) 
Notification code. 


SPBN_UPARROW Tells the application that the Up Arrow was clicked on, or 
the Up Arrow key was pressed. 


SPBN_DOWNARROW _ Tells the application that the Down Arrow was clicked on, 
or the Down Arrow key was pressed. 


SPBN_SETFOCUS Tells the application which spin field was selected. 
SPBN_KILLFOCUS Tells the application when the spin field loses focus. 


SPBN_ENDSPIN Tells the application that the user released the select 
button or one of the arrow keys while spinning a button. 
SPBN_CHANGE Tells the application that the contents of the spin field 
changed. ~ 
param2 


hwnd (HWND) 
Window handle. 


The interpretation of this handle is dependent upon the following notification codes: 
¢ SPBN_UPARROW, SPBN_DOWNARROW, and SPBN_ENDSPIN. 


The param2 parameter is the handle to the currently selected spin field in a 
particular master-servant setup. If either the Up or Down Arrow is clicked on 
and none of a spin button’s servants are currently selected, the master will 
return a handle to itself. 


¢ SPBN_SETFOCUS 
The param2 parameter is the handle of the currently selected spin field. 
This message tells the application which spin field is selected. 
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e SPBN_KILLFOCUS 


The param2 parameter is NULLHANDLE if the ey field loses focus or no spin 
field is currently selected. 


This message tells the application when a spin field loses focus. 


Note: Both SPBN_KILLFOCUS and SPBN_SETFOCUS are set independently. 
You must check this message only when the application does not 
specify a master-servant relationship. 


° SPBN_CHANGE 


The param2 parameter is the handle of the spin button in which the spin field 
text changed. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message is sent when, as specified by notifycode, the spin button component must tell 
its owner of a significant event. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return 0. 


Spin Button Control Window Messages 


This section describes the spin button control window procedure actions on receiving the 
following messages. 


SPBM_OVERRIDESETLIMITS 


This message causes the component to set or reset numeric limits. 


Parameters 
param1 


lUpLimit (LONG) 
Upper limit. 


param2 


ILowLimit (LONG) 
Lower limit. 
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Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion. 
FALSE _ Error occurred. 


Remarks 
The application sends this message to the component to set or reset numeric limits. 


This message is functionally identical to SPBM_SETLIMITS, except that the current value of 
the spin button does not change if it is out of range. 


When the upper limit is less than the lower limit, FALSE is returned. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 


SPBM_QUERYLIMITS 


This message enables an application to query the limits of a numeric spin field. 


Parameters 
param1 


plUpLimit (PLONG) 
Pointer to a LONG that will receive the returned upper limit. 


param2 


plLowLimit (PLONG) 
Pointer to a LONG that will receive the returned lower limit. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks ; 
The application sends this message to the component to determine the limits of a numeric 
spin field. 


When the spin button has no data, or when it is spinning an array, FALSE is returned. 
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Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE 


SPBM_QUERYVALUE | 


This message causes the component to show the value in the spin field. 


Parameters 
param1 


pStorage (PVOID) 
Place for returned value. 


A place for the returned value. This value is either the address of a string or the 
address of-a long variable. 


If the usBufSize is 0, param? is assumed to be an address of a long variable. 
If param1 is Other, it is assumed to be an address of a string. 


NULL Causes the spin button to process the reset or update as specified, but it 
will not try to return a value to the application. 


Other The address where the value is returned. 


param2 


. usBufSize (USHORT) 
Buffer size. 


If usBufSize is too small to return all of the text, the spin button returns as much of 
the text as it can. 


0 The spin button assumes that param1 is the address of a long variable. If 
the data in the spin button is spinning between an upper and lower limit, 
the current value is passed back in the variable. 


If the data in the spin button is in an array, the index of the current array 
value (or last valid value) is passed back in the variable. | 


Other The spin button assumes that param7 is the address of a string. The 
information passed back in the string is dependent upon the flags in the 
usValue parameter. 
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usValue (USHORT) 
Update/reset value. 


Controls how the spin field is updated. 


SPBQ_UPDATEIFVALID Update the contents of the spin field if the value is valid. 
This is the default. 


Specifying this flag on a query will not update the 
contents of the spin field if it is exactly the same as an 
item in the spin button list. 


If an item in the list is Monday, specifying 
SPBQ_UPDATEIFVALID updates the spin field contents 
when MONDAY, monday, or MONDAY are typed, but 
not when Monday is typed. This prevents recursion if 
the application checks for the validity each time a 
SPBN_CHANGE message is sent from the component. 


SPBQ_ALWAYSUPDATE Update the contents of the spin field if the value is valid. 
Reset the contents of the spin field to the last valid 
value if the field contains data that is not valid. 


If the spin button is spinning numbers between an upper 
and a lower limit, and the content of the spin field is a 
valid number that is out of range, the spin button does 
not reset itself to the last valid value. It sets the current 
position at the upper limit when the out-of-range number | 
specified is above the upper limit. It sets the current 
position at the lower limit when the out-of-range number 
is below the lower limit. 


When the current value is changed, the return of the 
query message is still FALSE. 


SPBQ_DONOTUPDATE _ Do not update the contents of the spin field, even if the 
value is valid. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion. 
FALSE — Error occurred. 


Remarks 

The application sends this message to the component to determine what value is in the spin 
field. The application sets up a field for the component to deposit the value, and sets a flag 
‘to determine what the function does when the value matches or does not match the given 
spin-list values. 


TRUE is returned when a matched value is found, or the data is in the range. 
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FALSE is returned when no match is found, the value is out of range, or no spin data exists. 


Default Processing 
The default window procedure does not expect to receive this mee and takes no action 
other than to return FALSE. 


SPBM_SETARRAY 


This message causes the component to set or reset the array of data. 


Parameters 
param1 


pStrl (PSZ) 
Pointer to the new array of values. 


param2 


usitems (USHORT) 
Number of items in the array. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The application sends this message to the component to set or reset the array of data. 


The component tries to leave the current value unchanged. However, if the current value is 
out of range for the new array, it is moved to the closest extreme. Thus, if the current value 
is less than 0, it is moved to 0. If the current value is greater than the previous value, it is 
set to the previous value. 


If the data exceeds 64KB, or if param? or param2 equal 0, FALSE is returned. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 
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SPBM_SETCURRENTVALUE 


This message causes the component to set or reset the current numeric value or array 
index. 


Parameters 
param1 


lValue (LONG) 
Array value or index. 


Current value or index of array. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The application sends this message to the component to set or reset the current numeric 
value or array index. 


FALSE is returned when the value is out of range or there is no spin data. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 


SPBM_SETLIMITS 


This message causes the component to set or reset numeric limits. 


Parameters 
param1 


IUpLimit (LONG) 
Upper limit. 
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param2 


ILowLimit (LONG) 
Lower limit. 


rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks . 

The application sends this message to the component to set or reset numeric limits. The 
component sets the current value to the content in the spin field when it is a valid number. 
When the current value is out of the range of the limits, it is moved to the nearest limit, upper 
or lower. 


If the upper limit is less than the lower limit, FALSE is returned. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 


SPBM_SETMASTER 


This message causes the component to identify its master. 


Parameters 
param 


hwnd (HWND) 
Handle of master component. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE —_ Successful completion 
FALSE — Error occurred. 
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Remarks 
The application sends this message to the component to tell a component who its master is. 


When the application wants to take control of the spin button, it must set the param? of each 
spin button to NULLHANDLE. This must be done, for example, when a spin button with a 
non-contiguous list of spin values is created (2, 4, 6, 8, 10...). When the param? of a spin 
button is NULLHANDLE, the spin button does not perform the following default functions: 


e Spin up or down on its own when the Up or Down Arrow key is pressed. 

¢ Spin up or down when the Up or Down Arrow of the master is pressed. 

e A master does not take the focus when its arrows are pressed and none of its servants 
have focus. 

e The spin button does not send itself an SPBM_QUERYVALUE message with the 
SPBQ_ALWAYSUPDATE flag to update the current value when an SPBM_SPINUP or 
SPBM_SPINDOWN message is received. 

¢ The spin button does not fast spin. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 


SPBM_SETTEXTLIMIT 


This message sets the maximum number of characters allowed in a spin field. 


Parameters 
param1 


usLimit (USHORT) 
Character limit. 


Number of characters to allow. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 
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Remarks 
The application sends this message to set the maximum number of characters allowed in the 
spin field. The size limit of the spin field is 255 characters. This is the default. 


When the size exceeds 255 characters, FALSE is returned, 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 


SPBM_SPINDOWN 


This message causes the component to show the previous value (spin backward). 


Parameters 
param1 


ulltem (ULONG) 
Number of values to spin down. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE Error occurred. 


Remarks 
The application sends this message to the component when it wants the previous value 
shown (spin backward). 


When there is no data to spin, FALSE is returned. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 


19-12 PM Programming Reference Vol I! 


SPBM_SPINUP 


This message causes the component to show the next value (spin forward). 


Parameters 
param1 


ulltem (ULONG) 
Number of values to spin up. | 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE _ Error occurred. 


Remarks 
The application sends this message to the component when it wants the next value shown 
(spin forward). 


When there is no data to spin, FALSE is returned. 


Default Processing 
The default window procedure does not expect to receive this message and takes no action 
other than to return FALSE. 
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Chapter 20. Static Control Window Processing 


This system-provided window procedure processes the actions on a static control . 


(WC_STATIC). 


Purpose 


Static controls are simple text fields, bit maps, icons, and boxes that can be used to label or 
box other controls. Static controls do not accept user input, nor do they send notification 


messages to their owner. 


Static Control Styles 


These static control styles are available: 


SS_TEXT 


SS_GROUPBOX 


SS_ICON 
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Creates a box with formatted text. The text is formatted before 
it is displayed according to the setting of these text 
drawing-style flags: 


DT_LEFT Left-justified text 

DT_CENTER Centered text 

DT_RIGHT Right-justified text 

ORed with one of: 

DT_TOP Text is aligned to top of window 

DT_VCENTER Text is aligned vertically in center of 
window 

DT_BOTTOM Text is aligned to bottom of window 


The following text drawing style can also be ORed, but only if 
DT_TOP and DT_LEFT are also specified: 


DT_WORDBREAK Text is multi-line with word-wrapping at 
ends of lines. 


Note: For “static” text that can be selected, a Button Control 
with a style of BS_NOBORDER can be used. 


A group box static control is a box that has an identifying text 
String in its upper left corner. Group boxes are used to collect 
a group of radio buttons or other controls into a single unit. 


Draws an icon. The text of the static control is a string that is 
used to derive the resource ID from which the icon is loaded. 
The format of the string is: 


e The first byte is OxFF, the second byte is the low byte of 
the resource ID, and the third byte is the high byte of the 
resource ID. 


e The first character is “#’; subsequent characters make up 
the decimal text representation of the resource ID. This 
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SS_SYSICON 


SS_BITMAP 


SS_FGNDRECT 
SS_BKGNDRECT 
SS_FGNDFRAME 
SS_BKGNDFRAME 
SS_HALFTONERECT 
SS_HALFTONEFRAME 
SS_AUTOSIZE 


Static Control Data 


None. 


Default Colors 


format can be used for specifying a system icon in a 
resource file. The decimal string is the value of the 
appropriate SPTR_* constant 


If the string is empty or does not follow the format above, no 
resource is loaded. 


The resource is assumed to reside in the resource file of the 
current process. 


This control is resized to the size of the icon. 


This style is the same as SS_ICON except that the icon ID is 
specified as one of the system pointer ID values (SPTR_* 
values) rather than a resource ID. This style provides a 
convenient way to include system icons in application dialog 
boxes. 


Draws a bit map. The text of the static control names the 
bit-map resource, as for SS_ICON. 


Creates a rectangle filled with the color of the foreground. 
Creates a rectangle filled with the color of the background. 
Creates a box with frame color equal to the foreground color. 
Creates a box with frame color equal to the background color. 
Creates a rectangle filled with halftone shading. 

Creates a box with halftone shading frame. 


The static control will be sized to make sure the contents fit. 


The following system colors are used when the system draws button controls: 


SYSCLR_WINDOWFRAME 
SYSCLR_WINDOWSTATICTEXT 


SYSCLR_WINDOW 


SYSCLR_BACKGROUND. 


Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_BORDERCOLOR 


PP_FOREGROUNDCOLOR. 
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Static Control Notification Messages 


No notification messages are initiated by the static control window procedure. 
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Static Control Window Messages 


This section describes the static control window procedure actions on receiving the following 
messages. 


SM_QUERYHANDLE 


This message returns the icon or bit-map handle of a static control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
hbmHandle (HBITMAP) 
Icon or bit-map handle of the static control. 


NULLHANDLE _ No icon or bit-map handle of the static control exists, or an error 
occurred. 
Other Icon or bit-map handle of the static control. 


_ Remarks 
The static control window procedure responds to this message by setting hbmHandle to the 
handle of the icon or bit-map of the static control. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set hbmHandle to the default value of NULLHANDLE. 
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SM_SETHANDLE 


This message sets the icon or bit-map handle of a static control. 


Parameters 
param1 


hbmHandle (HBITMAP) 
Icon or bit-map handle of a static control. 


This is an icon handle when sent to a control with a style of SS_ICON or 
SS_SYSICON, and a bit-map handle when sent to a control with a style of 
SS_ BITMAP. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
hbmHandle (HBITMAP) 
Icon or bit-map handle of the static control. 


NULLHANDLE _ No icon or bit-map handle of the static control exists, or an error 
occurred. 
Other Icon or bit-map handle of the static control. 


Remarks 

The static control window procedure responds to this message by setting the icon or bit-map 
handle of a static control to the value specified by hbmHandle, and causes the static control 
to be redrawn, using the new item handle. 


It should only be sent to a control with a style of SS_BITMAP, SS_ICON, or SS_SYSICON. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set hbmHandle to the default value of NULLHANDLE. 


WM_MATCHMNEMONIC (in Static Controls) 
For the cause of this message, see “WM_MATCHMNEMONIC’ on page 10-55. 


For a description of the parameters, see “WM_MATCHMNEMONIC’ on page 10-55. 


Remarks 
The static control window procedure responds to this message by setting rc as appropriate. 
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Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
¢ WM_MATCHMNEMONIC 


WM_QUERYCONVERTPOS (in Static Controls) 
For the cause of this message, see “WM_QUERYCONVERTPOS’ on page 10-72. 


For a description of the parameters, see “WM_QUERYCONVERTPOS’ on page 10-72. 


Remarks 
The static control window procedure returns QOCP_NOCONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS?’ on page 10-72. 


Related Messages 
* WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in Static Controls) 


This message occurs when an application queries the static control window procedure 
window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Remarks 
The static control window procedure responds to this message by passing it to the default 
window procedure. 


Default Processing 

The default window procedure sets the cchText, cbPresParams, and cbCilData parameters 
of the WNDPARAMS data structure, identified by pwndparams, to zero and sets rc to - 
FALSE. 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 
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WM_SETWINDOWPARAMS (in Static Controls) 


This message occurs when an application sets or changes the static control window 
procedure window parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS’ on page 10-86. 


Remarks 
The static control window procedure responds to this message by passing it to the default 
window procedure. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. 


Related Messages 
e WM_SETWINDOWPARAMS 
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Chapter 21. Title Bar Control Window Processing 


This system-provided window procedure processes the actions on a title bar control 
(WC_TITLEBAR). 


Purpose 
The title bar control is the frame control that is used to display the application window title. It 
is also used to display the active or inactive status of the frame window. 


The title bar control also implements the user interface for moving the frame window. 


The standard identifier for a title bar control in a frame window is FID_TITLEBAR. 


Title Bar Control Styles 


There is only one title bar style, the default. 


Title Bar Control Data 


None. 


Default Colors 
The following system colors are used when the system draws button controls: 


SYSCLR_ACTIVETITLETEXTBGND 
SYSCLR_ACTIVETITLE 
SYSCLR_ACTIVETITLETEXT | 
SYSCLR_ACTIVETITLETEXTBGND 
SYSCLR_INACTIVETITLE 
SYSCLR_INACTIVETITLETEXT 
SYSCLR_INACTIVETITLETEXTBGND 
SYSCLR_TITLEBOTTOM 
SYSCLR_(IN)ACTIVETITLETEXTBGND 
SYSCLR_(IN)ACTIVETITLE. 


Some of these defaults can be replaced by using the following presentation parameters in 
the application resource script file or source code: 


PP_FONTNAMESIZE 
PP_ACTIVECOLOR 
PP_INACTIVECOLOR 
PP_ACTIVETEXT*COLOR 
PP_INACTIVETEXT*COLOR 
PP_ACTIVETEXTFGNDCOLOR 
PP_INACTIVETEXTFGNDCOLOR 
PP_BORDERCOLOR. 
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Title Bar Control Notification Messages 


These messages are initiated by the title bar control to notify its owner of significant events. 


WM_SYSCOMMAND (in Title Bar Controls) 
For the cause of this message, see “WM_SYSCOMMAND” on page 10-91. 


For a description of the parameters, see “WM_SYSCOMMAND?” on page 10-91. 


The title bar control window procedure sets uscmd to the title bar control identity and 
ussource to CADSRC_OTHER. . 


Remarks 

The title bar contro! window procedure generates this message when a mouse input 
message is received. The window procedure posts the message to the queue of the window 
owner. 


The purpose of this message is to notify the owner window to maximize or restore depending 
on its current state. 


Default Processing 
The default window procedure takes no action on this message, other than to set u/Reserved 
to 0. 


Related Messages 
* WM_COMMAND 


WM_TRACKFRAME (in Title Bar Controls 
For the cause of this message, see “WM_TRACKFRAME?” on page 10-95. 


For a description of the parameters, see “WM_TRACKFRAME” on page 10-95. 


Remarks 
The title bar control window procedure generates this message and sends it to its owner, 
informing the owner that a mouse button down message has been received. 


Default Processing 
The default window procedure takes no action on this message, other than to set rc to 
FALSE. | 


Related Messages 
¢ WM_QUERYTRACKINFO 
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Title Bar Control Window Messages 


This section describes the title bar control window procedure actions on receiving the 
following messages. 


TBM_QUERYHILITE 


This message returns the highlighting state of a title-bar control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Highlighting state. 


TRUE Title-bar control is highlighted 
FALSE _ Title-bar control is not highlighted. 


Remarks 
The title bar control window procedure responds to this message by returning the highlighting 
state of the title-bar window. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 
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TBM_SETHILITE 


This message is used to highlight or unhighlight a title-bar control. 


Parameters 
param’ | 


usHighlighted (USHORT) 
Highlighting indicator. 


TRUE Highlight the title-bar control 
FALSE Remove highlight from the title-bar control. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 

The title bar control window procedure responds to this message by setting the highlighting 
state according to usHighlighted. If the title bar highlighting state is changed by this 
message, the title bar will repaint. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it, other than to set rc to the default value of FALSE. 


WM_QUERYCONVERTPOS (in Title Bar Controls) 
For the cause of this message, see “WM_QUERYCONVERTPOS’ on page 10-72. 


For a description of the parameters, see “WM_QUERYCONVERTPOS” on page 10-72. 


Remarks 
The title bar control window procedure returns QCP_NOCONVERT. 


Default Processing 
For the default window procedure processing of this message see 
“WM_QUERYCONVERTPOS’ on page 10-72. 
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Related Messages 
e WM_QUERYCONVERTPOS 


WM_QUERYWINDOWPARAMS (in Title Bars) 


This message occurs when an application queries the title bar control window procedure 
window parameters. 


For a description of the parameters, see “WM_QUERYWINDOWPARAMS?’ on page 10-75. 


Default Processing 

The title bar control window procedure queries the appropriate window parameters in 
accordance with pwndparams and sets rc to TRUE if the operation is successful, otherwise 
to FALSE. . 


Related Messages 
¢ WM_QUERYWINDOWPARAMS 


WM_SETWINDOWPARAMS (in Title Bar Controls) 
This message occurs when an application sets or changes the title bar control window 
procedure window parameters. 


For a description of the parameters, see “WM_SETWINDOWPARAMS” on page 10-86. 


Default Processing 

The title bar control window procedure sets the appropriate window parameters in 
accordance with pwndparams and sets rc to TRUE if the operation is successful, otherwise 
to FALSE. 


Related Messages 
e WM_SETWINDOWPARAMS 
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Chapter 22. Container Control Window Processing 


This system-provided window procedure processes the actions on a container control 
(WC_CONTAINER). 


Purpose 


A container control is a visual component whose specific purpose is to hold objects. These 

objects, or container items, can be anything that either your application or a user might store 
in a container. Examples are executable programs, word processing files, graphics images, 

and database records. 


Container item data is stored in RECORDCORE or MINIRECORDCORE data structures. 
Both the application and the container have access to the data stored in these records. See 
“RECORDCORE?” on page A-175 and “MINIRECORDCORE?” on page A-124 for descriptions 
of these data structures. 


Note: If the CCS MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


The maximum number of records is limited by the amount of memory in the user’s computer. 
The container control does not limit the number of records that a container can have. 


The following list shows which types of data can be displayed for each container view. Refer 
to the description of the container control in the OS/2 Programming Guide for more 
information about the types of views. 


View Types Data 


Icon view Icons or bit maps with text strings beneath 

Name view Icons or bit maps with text strings to the right 

Text view Text strings 

Tree view Icons or bit maps, and text strings 

Details view Icons or bit maps, text strings, numbers, times, and dates. 


Direct editing of container item text is supported in all views, including blank text fields. 


The container control is designed according to the Common User Access (CUA) guidelines. 
For example, the CUA direct manipulation protocol is fully supported, enabling a user to 
visually drag an object in a container window and drop it on another object or container 
window. In addition, the container control supports CUA-defined selection types and 
techniques for selecting container items, as well as selection mechanisms, such as pointing 
devices and the keyboard, and multiple forms of emphasis. For a complete description of 
CUA containers, refer to the SAA CUA Guide to User Interface Design and to the SAA CUA 
Advanced Interface Design Reference. 
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The container control automatically provides or enables either horizontal or vertical scroll 
bars, or both, whenever all or part of one or more container items are not visible in a 
container window’s client area. 


Container Control Window Words 


The container control reserves 4 bytes in its window words for application use. This memory 
can be accessed using the WinSetWindowULong and WinQueryWindowULong functions at 
offset QWL_USER. 


Container Control Styles and Selection Types 


Containers are WC_CONTAINER class windows that have the following CCS_container 


styles and selection types. Container control styles and selection types are specified when 
the container control is created. 


Container Control Styles 


The following list defines container style bits that your application can use. These style bits 
must be set by your application. 


CCS_AUTOPOSITION 


Automatic positioning, which causes container items displayed in the icon view to be 
arranged when any of the following occur: 


e¢ The window size changes 

e Container items are inserted, removed, sorted, invalidated, or filtered 
e The font or font size changes 

e The window title text changes. 


In all of these cases, container items are arranged the same as when the 
CM_ARRANGE message is sent. The CCS_AUTOPOSITION style bit is valid only when 
it is used with the icon view (CV_ICON). 


CCS_MINIRECORDCORE 
A record style bit that causes the container to interpret all container records as being 
smaller than they would otherwise be. If a CM_ALLOCRECORD message is received, 
all records are interpreted and allocated according to the information in the 
MINIRECORDCORE data structure instead of the RECORDCORE data structure, which 
is used if this style bit is not specified. 


CCS_READONLY 
A read-only style bit for an entire container, which prevents a user from editing any of the 
text in a container window. If you do not set this style bit, a user can edit any of the text 
in a container window unless you set the following read-only attributes in the appropriate 
data structures: 
CA_TITLEREADONLY 


Sets the container title to read-only. This is an attribute of the CNRINFO data 
structure’s flWindowAlttr field. 
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CRA_RECORDREADONLY 
Sets text fields in records to read-only. This is an attribute of the RECORDCORE 
and MINIRECORDCORE data structures’ ffRecordAttr field. 


Note: If the CCS_MiINIRECORDCORE style bit is specified when a container is 
created, the MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


CFA_FIREADONLY 
Sets column data to read-only. This is an attribute of the FIELDINFO data 
structure’s ffData field. 


CFA_FITITLEREADONLY . 
Sets column headings to read-only. This is an attribute of the FIELDINFO data 
structure’s ffTitle field. 


CCS_VERIFYPOINTERS 
A pointer verification style bit, which verifies that the application pointers are members of 
the container’s linked list before they are used. If it is not set, the container does not 
verify the pointers. 


Notes: 


1. The CCS_VERIFYPOINTERS style bit does not verify the validity of a pointer. It 
only verifies whether a pointer is a member of a container’s linked list. 


2. After your code has been developed and tested, you may want to remove the 
CCS_VERIFYPOINTERS style bit in order to improve the container’s performance. 
Otherwise, the container will attempt to verify all pointers, which will slow its 
response to actions that users perform. 


Container Control Selection Types 
If a selection type is not specified, single selection is the default. For the tree view, single 
selection is the only type supported. Refer to the description of the selection types in the 
SAA CUA Advanced Interface Design Reference for more information. 


CCS_SINGLESEL 
Single selection, which allows a user to select only one container item at a time. Each 
time a user selects a container item, the selection of any other container item is 
cancelled. 


CCS_EXTENDSEL 
Extended selection, which allows a user to select one or more container items. A user 
can select one item, a range of items, or multiple ranges of items. 


CCS_MULTIPLESEL 
Multiple selection, which allows a user to select zero or more container items. 
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Container Control Data 
See the following for information on the container control data structures: 


“CDATE” on page A-25 
-“CNRDRAGINFO” on page A-28 
“CNRDRAGINIT” on page A-32 
“CNRDRAWITEMINFO?’ on page A-28 
“CNREDITDATA’ on page A-29 
“CNRINFO” on page A-33 

“CTIME” on page A-44 

“FIELDINFO” on page A-72 
“FIELDINFOINSERT” on page A-75 
“MINIRECORDCORE”’ on page A-124 
“NOTIFYDELTA’ on page A-130 
“NOTIFYRECORDEMPHASIS’ on page A-131 
“NOTIFYRECORDENTER’” on page A-132 
“NOTIFYSCROLL’ on page A-133 
“OWNERBACKGROUND” on page A-135 
“QUERYRECFROMRECT” on page A-173 
“QUERYRECORDRECT” on page A-174 
“RECORDCORE?” on page A-175 
“RECORDINSERT” on page A-177 
“SEARCHSTRING” on page A-184 
“TREEITEMDESC” on page A-199. 
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Container Control Notification Messages | 


These messages are initiated by the container control window to notify its owner of 
significant events. 


WM_CONTROL (in Container Controls) 
For the cause of this message, see WM_CONTROL. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


notifycode (USHORT) 


Notify code. 


The container control uses the following notification codes. For the complete 
description of the specified notifycode, see “Container Control Notification Codes” on 


page 22-10. 
CN_BEGINEDIT 
CN_COLLAPSETREE 
CN_CONTEXTMENU 
CN_DRAGAFTER 


CN_DRAGLEAVE 
CN_DRAGOVER 


CN_DROP 
CN_DROPNOTIFY 
~ CN_DROPHELP 
CN_EMPHASIS 
CN_ENDEDIT 


Container text is about to be edited. 
A parent item was collapsed in the tree view. 
The container received a WM_CONTEXTMENU message. 


The container received a DM_DRAGOVER message. The 
CN_DRAGAFTER notification code is sent only if either 
the CA_LORDEREDTARGETEMPH or 
CA_MIXEDTARGETEMPH attribute of the CNRINFO data 
structure is set and the current view is the name, text, or 
details view. . 


The container received a DM_DRAGLEAVE message. 


The container received a DM_DRAGOVER message. The 
CN_DRAGOVER notification code is sent only if the 
CA_ORDEREDTARGETEMPH attribute of the CNRINFO 
data structure is not set or the current view is the icon 
view or tree view. 


The container received a DM_DROP message. 

The container received a DM_DROPNOTIFY message. 
The container received a DM_DROPHELP message. 
A container record’s attributes changed. 


Direct editing of container text has ended. 
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CN_ENTER 


CN_EXPANDTREE 
CN_HELP 
CN_INITDRAG © 


CN_KILLFOCUS 
CN_PICKUP 
CN_QUERYDELTA 


CN_REALLOCPSZ 


CN_SCROLL 
CN_SETFOCUS 


param2 


notifyinfo (ULONG) 
Notify code information. 


The Enter key is pressed while the container window has 
the focus, or the select button is double-clicked while the 
pointer is over the container window. 


A parent item is expanded in the tree view. 
The container received a WM_HELP message. 


The drag button was pressed and the pointer was moved 
while the pointer was over the container control. 


The container is losing the focus. 
The container received a WM_PICKUP message. 


Queries for more data when a user scrolls to a preset 
delta value. 


Container text is edited. This message is sent before the 
CN_ENDEDIT notification code is sent. 


The container window scrolled. 


The container is receiving the focus. 


For the definition of this parameter, see the description of the specified 
notifycode“Container Control Notification Codes” on page 22-10. 


Returns 
ulReserved (ULONG) 


Reserved value, should be 0. 


Remarks 


The container control window procedure generates this message and sends it to ts owner, 


informing the owner of this event. 


Default Processing 


For a description of the default processing, see WM_CONTROL. 


WM_CONTROLPOINTER (in Container Controls) 
For the cause of this message, see WM_CONTROLPOINTER. 


For a description of the parameters, see WM_CONTROLPOINTER. 
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Remarks 
For the appropriate remarks, see WM_CONTROLPOINTER. 


Default Processing 
For the default processing, see WM_CONTROLPOINTER. 


WM_DRAWITEM (in Container Controls) 
For the cause of this message, see WM_DRAWITEM. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


param2 


pOwnerltem (POWNERITEM) 
Pointer to an OWNERITEM data structure. 


The following list defines the OWNERITEM data structure fields as they apply to the 
container control. See OWNERITEM for the default field values. 


hwnd (HWND) 
Handle of the window in which ownerdraw will occur. The following is a list of 
the window handles that can be specified for ownerdraw: 


The container window handle of the icon, name, text, and tree views 
The container title window handle 

The left or right window handles of the details view 

The left or right column heading windows of the details view. 


hps (HPS) 
Handle of the presentation space of the container window. For the details view 
that uses a split bar, the presentation space handle is either for the left or right 
window, depending upon the position of the column. If the details view does 
not have a split bar, the presentation space handle is for the left window. 


fsState (ULONG) 
Specifies emphasis flags. This state is not used by the container control 
because the application is responsible for drawing the emphasis states during 
ownerdraw. 

fsAttribute (ULONG) 
Attributes of the record as given in the ffRecordAtir field in the RECORDCORE 
data structure. 
Note: If the CCS_MINIRECORDCORE style bit is specified when a container 


is created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
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PRECORDCORE in all applicable data structures and messages. See 
“RECORDCORE” on page A-175 and “MINIRECORDCORE?” on 
page A-124 for descriptions of these data structures. 


fsStateOld (ULONG) 
Previous emphasis. This state is not used by the container control because 
the application is responsible for drawing the emphasis states during 
ownerdraw. 


fsAttributeOld (ULONG) 
Previous attribute. This state is not used by the container control because the 
application is responsible for drawing the emphasis states during ownerdraw. 


rcilltem (RECTL) 
This is the bounding rectangle into which the container item is drawn. 


If the container item is an icon/text or bit-map/text pair, two WM_DRAWITEM 
messages are sent to the application. The first WM_DRAWITEM message 
contains the rectangle bounding the icon or bit map and the second contains 
the rectangle bounding the text. 


If the container item contains only text, or only an icon or bit map, only one 
WM_DRAWITEM message is sent. However, if the current view is the tree 
icon or tree text view and if the item is a parent item, the application will 
receive an additional WM_DRAWITEM (in Container Controls) message. The 
additional message is for the icon or bit map that indicates whether the parent 
item is expanded or collapsed. 


If the current view is the details view and the CFA_OWNER attribute is set, the 
rectangle’s size is equal to the width of the column and the height of the tallest 
field in the container item. CFA_OWNER is an attribute of the FIELDINFO 
data structure’s fiData field. 


iditem (ULONG) 
Identifies the item being drawn. It can be one of the following: 


CMA_CNATITLE 
CMA_ICON 
CMA_TEXT 
CMA_TREEICON. 


This field is not used for the details view and is set to 0. 


hitem (CNRDRAWITEMINFO) 
Pointer to a CNRDRAWITEMINFO structure. This field is set to NULL if id/tem 
is CMA_CNRTITLE. 


See “CNRDRAWITEMINFO” on page A-28 for descriptions of this structure’s 
fields. 
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Returns 
re (BOOL) 
Item-drawn indicator. 


TRUE The owner draws the item, and so the container control does not draw it. 
FALSE __ If the owner does not draw the item, the owner returns this value and the 
container control draws the item. 


Remarks 
CA_OWNERDRAW is an attribute of the CNRINFO data structure’s flWindowAttr field. 


The container control window procedure generates this message and sends it to the owner 
of the container control to offer the owner the opportunity to draw that item. 


Default Processing 
For a description of the default processing, see WM_DRAWITEM. 
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Container Control Notification Codes 


The following WM_CONTROL (in Container Controls) notification codes are sent by the 
container control to its owner. 


CN_BEGINEDIT 


The container control sends the WM_CONTROL (in Container Controls) message with the 
CN_BEGINEDIT notification code to its owner whenever container text is about to be edited. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_BEGINEDIT (USHORT) 
Notification code. 


param2 


pCnrEditData (PCNREDITDATA) 
Pointer to the CNREDITDATA structure. 


See “CNREDITDATA’” on page A-29 for definitions of this structure’s fields as they 
apply to the CN_BEGINEDIT notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The CN_BEGINEDIT notification code is sent when direct editing of container text begins. 
Warning: Once your application receives the CN_BEGINEDIT notification code, it must not 
send any messages to the container until it receives the CN_ENDEDIT notification code, 
which indicates that direct editing of container text has ended. If any messages are sent to 
the container before your application receives the CN_ENDEDIT notification code, the results 
of direct editing are unpredictable. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_COLLAPSETREE 


The container control sends the WM_CONTROL (in Container Controls) message with the 
CN_COLLAPSETREE notification code to its owner whenever the container collapses a 
parent item in the tree view. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_COLLAPSETREE (USHORT) 
Notification code. 


param2 


pRecord (PRECORDCORE) 
Pointer to the record that was collapsed. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN _CONTEXTMENU 


The container control sends the WM_CONTROL (in Container Controls) message with the 
CN_CONTEXTMENU notification code to its owner when the container receives a 
WM_CONTEXTMENU message. 


Parameters 
param1 


id (VSHORT) 
Container control ID. 


CN_CONTEXTMENU (USHORT) 
Notification code. 


param2 


pRecord (PRECORDCORE) 
Pointer to the RECORDCORE structure. 


If the user is using a pointing device, this RECORDCORE structure is the structure 
that the pointing device pointer is over. If the pointing device pointer is over white 
space, this field is NULL. 


If the user is using the keyboard, this RECORDCORE structure is the structure that 
has the selection cursor. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_DRAGAFTER 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_DRAGAFTER notification code to its owner whenever the container receives a 
DM_ | DRAGOVER message. The CN_DRAGAFTER notification code is sent only if the 
CA_ ~ORDEREDTARGETEMPHASIS or CA_MIXEDTARGETEMPHASIS attribute of the 
CNRINFO data structure is set and the current view is the name, text, or details view. 
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Parameters 
param1 


id (USHORT) 


Container control ID. 


CN_DRAGAFTER (USHORT) 


Notification code. 


param2 


pCnrDraginfo (PCNRDRAGINFO) 
Pointer to a CNRDRAGINFO structure. 


See “CNRDRAGINFO” on page A-28 for definitions of this structure’s fields as they 
apply to the CN_DRAGAFTER notification code. 


Returns 
ReturnCode 


usDrop (USHORT) 
Drop indicator. 


DOR_DROP 


DOR_NODROP 


DOR_NODROPOP 


The record can be dropped. The drop will not occur unless 
DOR_DROP is returned. When this response is returned, 
the container control applies ordered target emphasis to the 
target record. 


The record is acceptable and the current operation is 
supported by the target, but the record cannot be dropped in 
the current location. For example, the container control 
returns DOR_NODROP if the record being dragged is 
positioned over another record on which it cannot be 
dropped. 


If the container returns DOR_NODROP, the 
DM_DRAGOVER message will continue to be sent to it 
when the user does any of the following: 


e Moves the pointer 

e Presses a keyboard key 

e¢ Moves the pointer out of and back into the container 
window. 


The record is acceptable, but the target does not support the 
current operation. This response implies that the drop may 
be valid if the drag operation changes. For example, if the 
default operation is copy and the target does not support this 
operation, the drop may become valid if the user presses a 
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keyboard augmentation key to change to a different 
operation, such as move. 


If the container returns DOR_NODROPOP, no further 
DM_DRAGOVER messages are sent until the user does any 
of the following: . 


e Presses a keyboard key 
e Moves the pointer out of and back into the container 
window. 


DOR_NEVERDROP _ The record cannot be dropped. Ordered target emphasis is 
not drawn. If the container returns DOR_NEVERDROP, no 
further DM_DRAGOVER messages are sent until the user 
drags the record outside of and back into the container . 
window. 


usDefaultOp (USHORT) 
Default operation. 


Target-defined default operation. 


DO_COPY Operation is a copy. 

DO DEFAULT Operation is the default drag operation. No modifier keys are 
pressed. 

DO_LINK Operation is a link. 

DO_MOVE Operation is a move. 


DO_UNKNOWN Operation is application-defined. 


Remarks . 

The container control draws ordered target emphasis of container records. The target 
emphasis provided by the container control is a black line that is drawn below the target 
record. Therefore, it is not necessary for the application to draw any emphasis for the 
container when it receives this notification code. 


If the container returns anything except DOR_DROP, the target emphasis is automatically 
changed to a symbol that indicates no drop is allowed. This gives the user a visual cue that 
a drop cannot occur. The symbol reverts to the black line when the container returns a 
DOR_DROP reply. 


The CN_DRAGAFTER notification code is sent only for the details, name, and text views 
when the CA_ORDEREDTARGETEMPHASIS or CA_MIXEDTARGETEMPHASIS attribute of 
the CNRINFO data structure is set. If this attribute is not set, the CN_DRAGOVER 
notification code is sent. 


Default Processing : 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_DRAGLEAVE 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_DRAGLEAVE notification code to its owner when the container receives a 
DM_DRAGLEAVE message. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_DRAGLEAVE (USHORT) 
Notification code. 


param2 


pCnrDraginfo (PCNRDRAGINFO) 
Pointer to a CNRDRAGINFO structure. 


See “CNRDRAGINFO” on page A-28 for definitions of this structure’s fields as they 
apply to the CN_DRAGLEAVE notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This notification code is sent to the owner of the container control in response to a 
DM_DRAGLEAVE message. It informs the owner that one of the following has occurred: 


e Accontainer record was being dragged over the container and has left the container’s 
boundaries. 


e¢ The drag ended when help was requested or a user pressed the Esc key while the 
container record was over the container. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_DRAGOVER | 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_DRAGOVER notification code to its owner when the container receives a 
DM_DRAGOVER message. The CN_DRAGOVER notification code is sent only if the 
CA_ORDEREDTARGETEMPH attribute of the CNRINFO data structure is not set or the 
current view is the icon view or tree view. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_DRAGOVER (USHORT) 
Notification code. 


param2 


pCnrDraginfo (PCNRDRAGINFO) 
Pointer to a CNRDRAGINFO structure. 


See “CNRDRAGINFO” on page A-28 for definitions of this structure’s fields as they 
apply to the CN_DRAGOVER notification code. 


Returns 
ReturnCode 


usDrop (USHORT) 
Drop indicator. 


DOR_DROP The record can be dropped. When this response is 
returned, the container control applies target emphasis. 


DOR_NODROP The record is acceptable and the current operation is 
supported by the target, but the record cannot be dropped in 
the current location. For example, the container control 
returns DOR_DROP if the record being dragged is 
positioned over another record on which it cannot be 
dropped. 


If the container returns DOR_NODROP, the 
DM_DRAGOVER message will continue to be sent to it 
when the user does any of the following: 


e¢ Moves the pointer 

e Presses a keyboard key 

¢ Moves the pointer out of and back into the container 
window. 
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DOR_NODROPOP The record is acceptable, but the target does not support the 
current operation. This response implies that the drop may 
be valid if the drag operation changes. For example, if the 
default operation is copy and the target does not support this 
operation, the drop may become valid if the user presses a 
keyboard augmentation key to change to a different 
operation, such as move. 


If the container returns DOR_NODROPOP, no further 
DM_DRAGOVER messages are sent until the user does any 
of the following: 


e Presses a keyboard key 
¢ Moves the pointer out of and back into the container 
window. 


DOR_NEVERDROP _ The record cannot be dropped. Target emphasis is not 
drawn. If the container returns DOR_NEVERDROP, no 
further DM_DRAGOVER messages are sent until the user 
drags the record outside of and back into the container 
window. 


usDefaultOp (USHORT) 
Default operation. 


Target-defined default operation. 


DO_COPY Operation is a copy. 

DO DEFAULT Operation is the default drag operation. No modifier keys are 
pressed. 

DO_LINK Operation is a link. 

DO_MOVE Operation is a move. 


DO_UNKNOWN Operation is application-defined. 


Remarks 

This notification code shows where direct manipulation is occurring by applying target 
emphasis to indicate whether an item that is being dragged over the container can be 
dropped. It is not necessary for the application to draw any target emphasis for the container 
when it receives this notification code. 


If the pointer is over a container record and the item that is being dragged can be dropped 
on that record, the container draws a black rectangle around the target record. If the pointer 
is over white space and the item that is being dragged can be dropped on the white space, 
the container draws a black border around the edge of the client area. 


If the container returns anything except DOR_DROP, the target emphasis is automatically 
changed to a symbol that indicates no drop is allowed. This gives the user a visual cue that 
a drop cannot occur. The symbol reverts to the black rectangle or black border when the 
container returns.a DOR_DROP reply. 
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The CN_DRAGOVER notification code is sent only for the icon and tree views, or when the 
CA_ORDEREDTARGETEMPH attribute of the CNRINFO data structure is not set. If this 
attribute is set and the current view is the name, text, or details view, the CN_DRAGAFTER 
notification code is sent. 


The return parameter is reserved. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN DROP 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_DROP notification code to its owner when the container receives a DM_DROP message. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_DROP (USHORT) 
Notification code. 


param2 


pCnrDragInfo (PCNRDRAGINFO) 
Pointer to a CNRDRAGINFO structure. 


See “CNRDRAGINFO” on page A-28 for definitions of this structure’s fields as they 
apply to the CN_DROP notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This notification code is sent to the container’s owner when dragged container records are 
dropped over the container window. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_DROPNOTIFY 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_DROPNOTIFY notification code to its owner when a pickup set is dropped over the 
container. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_DROPNOTIFY (USHORT) 
Notification code. 


param2 


pCnrLazyDragInfo (PCNRLAZYDRAGINFO) 
Pointer to the CNRLAZYDRAGINFO structure. 


This structure contains information about the DRAGINFO, the RECORDCORE that 
was dropped on, and the window handle of the target window. 


Returns 
ulReserved (ULONG) ~ 
Reserved value, must be 0. 


Remarks 
This notification code is sent to the owner of the container when a lazy drag set is dropped 
over the container. (The container control receives a DM_DROP message.) 


Default Processing 
The default window procedure does not expect to receive this notification and so takes no 
action on it other than returning 0. 


CN_DROPHELP 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_DROPHELP notification code to its owner when the container receives a 
DM_DROPHELP message. 


Parameters 
param1 


id (USHORT) 
Container control ID. 
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CN_DROPHELP (USHORT) 
Notification code. 


param2 


pCnrDraginfo (PCNRDRAGINFO) 
Pointer to a CNRDRAGINEFO structure. 


See “CNRDRAGINFO” on page A-28 for definitions of this structure’s fields as they 
apply to the CN_DROPHELP notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This notification code is sent to the container’s owner when help for direct manipulation is 
requested over the container window. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_EMPHASIS 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_EMPHASIS notification code to its owner whenever a container record’s attributes 
change. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_EMPHASIS (USHORT) 
Notification code. 


param2 


pNotifyRecordEmphasis (PNOTIFYRECORDEMPHASIS) 
Pointer to the NOTIFYRECORDEMPHASIS structure. 


See “NOTIFYRECORDEMPHASIS’ on page A-131 for definitions of this structure’s 
fields as they apply to the CN_EMPHASIS notification code. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_ENDEDIT 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_ENDEDIT notification code to its owner whenever direct editing of container text has 
ended. 


Parameters 
param1 


id (USHORT) 
Container control !D. 


CN_ENDEDIT (USHORT) 
Notification code. 


param2 


pCnrEditData (PCNREDITDATA) 
Pointer to the CNREDITDATA structure. 


See “CNREDITDATA’” on page A-29 for definitions of this structure’s fields as they 
apply to the CN_ENDEDIT notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

Direct editing of container text is completed. Any changes made to the text are saved when 
a user presses the select button outside the window that contains the multiple-line entry 
(MLE) field used to edit text in a container. However, a user can end the direct editing of 
text without saving any changes to the text by doing any of the following: 


e Pressing the Esc key 

e¢ Dragging the container item that is being edited 

e Pressing the Alt key and the select button before direct editing of container text has 
ended 

e Scrolling the container window. 
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The CN_ENDEDIT notification code is sent to the application in each of these cases. 


Default Processing 3 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN ENTER 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_ENTER notification code to its owner when either of the following occurs: 


e The Enter key is pressed while the container window has the focus 
e The select button is double-clicked while the pointer is over the container window. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_ENTER (USHORT) 
Notification code. 


param2 


pNotifyRecordEnter (PNOTIFYRECORDENTER) 
Pointer to the NOTIFYRECORDENTER structure. 


See “NOTIFYRECORDENTER’ on page A-132 for definitions of this structure’s 
fields as they apply to the CN_ENTER notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_EXPANDTREE 


The container control sends the WM_CONTROL (in Container Controls) message with the 
CN_EXPANDTREE notification code to its owner whenever the container expands a parent 
item in the tree view. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_EXPANDTREE (USHORT) 
Notification code. 


param2 


pRecord (PRECORDCORE) 
Pointer to the record that was expanded. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_HELP } 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_HELP notification code to its owner whenever the container receives a WM_HELP 
message. 


Parameters 
param1 


id (USHORT) 
Container control ID. 
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CN_HELP (USHORT) 
Notification code. 


param2 


pRecord (PRECORDCORE) 
Pointer to the record that has the selection cursor. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. — 


Remarks 
This notification code is sent to the container’s owner when help is requested for a container 
item. 


Default Processing | 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_INITDRAG 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_INITDRAG notification code to its owner when the drag button is pressed and the pointer 
is moved while the pointer is over the container control. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_INITDRAG (USHORT) 
Notification code. 


param2 


pCnrDraginit (PCNRDRAGINIT) 
Pointer to the CNRDRAGINIT structure. 


See “CNRDRAGINIT” on page A-32 for descriptions of this structure’s fields as they 
apply to the CN_INITDRAG notification code. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This notification code is sent to the container’s owner when the drag button is pressed and 
the pointer is moved while the pointer is over the container control. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_KILLFOCUS 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_KILLFOCUS notification code to its owner whenever the container is losing the focus. 


Parameters 
param1 


id (USHORT) 
Container contro! ID. 


CN_KILLFOCUS (USHORT) 
Notification. code. 


param2 


hwndCnr (HWND) 
Container control handle. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_PICKUP 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_PICKUP notification code to its owner when a pickup and drop operation is initiated over 
a container. , 


Parameters 
param 


id (UVSHORT) 
Container control !D. 


CN_PICKUP (USHORT) 
Notification code. 


param2 


iad aida tie (PCNRDRAGINIT) 
Pointer to the CNRDRAGINIT structure containing direct- -manipulation information 
initiated in a container. 


The CNRDRAGINIT structure is the same as the one used for standard drag 
notifications. 


Returns 
returns 


ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks 
This notification code is sent to the owner of the container when a lazy drag operation is 
commenced over a container. (The container control receives a WM_PICKUP message.) 


The CN_PICKUP message handler determines if the mouse is over an object or in white 
space of the client window. 


lf a pickup object is not selected, only that pickup object is added to the lazy drag set. If the 


pickup object is selected, all selected items in the container are added to the lazy drag set. 
The shell sets the CRA_PICKED attributes for all objects that are picked. 


Default Processing 
The default message procedure sets ulReserved to 0. 
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CN_QUERYDELTA 
The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_QUERYDELTA notification code to its owner to query for more data when a user scrolls 
to a preset delta value. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_QUERYDELTA (USHORT) 
Notification code. 


param2 


pNotifyDelta (PNOTIFYDELTA) 
Pointer to the NOTIFYDELTA structure. 


See “NOTIFYDELTA’” on page A-130 for definitions of this structure’s fields as they 
apply to the CN_QUERYDELTA notification code. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The delta value is specified by the cDelta field of the CNRINFO data structure and is set with 
the CMA_DELTA attribute of the CM_SETCNRINFO message. If the value of the cDelta 
field is greater than O and a user scrolls to the threshold record, the container control sends 
a CN_QUERYDELTA notification code to the application. The application can then insert 
more records into the container. It may be necessary for the application to remove some 
records before inserting records. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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CN_REALLOCPSZ 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_REALLOCPSZ notification code to its owner whenever container text is edited. It is sent 
before the CN_ENDEDIT notification code is sent. 


Parameters 
param1 


id (UVSHORT) 
Container control ID. 


CN_REALLOCPSZ (USHORT) 
Notification code. 


param2 


pCnrEditData (PCNREDITDATA) 
Pointer to the CNREDITDATA structure. 


See “CNREDITDATA’ on page A-29 for definitions of this structure’s fields as they 
apply to the CN_REALLOCPSZ notification code. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE _ The application has sufficient memory for the new text string. 
FALSE The application has insufficient memory for the new text string or does not 
want the string to be copied. 


Remarks 

The CN_REALLOCPSZ notification code is sent after direct editing of container text is 
complete. It notifies the application that the container is about to copy the changed text to 
the application’s text string. This allows the application to ensure that the correct amount of 
memory is allocated to accommodate the change. 


if TRUE is returned by the application, the container control copies the new text to the 
application’s text string. However, if the application returns FALSE, changed text is 
disregarded. Warning: Once your application receives the CN_REALLOCPSZ notification 
code, it must not send any messages to the container until it receives the CN_ENDEDIT 
notification code, which indicates that direct editing of container text has ended. If any 
messages are sent to the container before your application receives the CN_ENDEDIT 
notification code, the results of direct editing are unpredictable. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return FALSE. 
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CN SCROLL 


The container control sends a WM_CONTROL (in Container Controls) message with the 
CN_SCROLL notification code to its owner whenever the container window scrolls. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_SCROLL (USHORT) 
Notification code. 


param2 


pNotifyScroll (PNOTIFYSCROLL) 
Pointer to the NOTIFYSCROLL structure. 


See “NOTIFYSCROLL” on page A-133 for definitions of this structure’s fields as 
they apply to the CN_SCROLL notification code. 


Returns 
re (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 


CN_SETFOCUS 


The container control sends a WM_CONTROL (in Container Controls) message with the — 
CN_SETFOCUS notification code to its owner whenever the container receives the focus. 


Parameters 
param1 


id (USHORT) 
Container control ID. 


CN_SETFOCUS (USHORT) 
Notification code. 
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param2 


hwndCnr (HWND) 
Container control handle. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure does not expect to receive this notification code and therefore 
takes no action on it other than to return 0. 
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Container Control Window Messages 


This section describes the container control window procedure actions on receiving the 
following messages. . 


CM_ALLOCDETAILFIELDINFO 


This message allocates memory for one or more FIELDINFO structures. 


Parameters 
param1 


nFieldinfo (USHORT) 
Number of FIELDINFO structures to be allocated. 


The value of this parameter must be greater than 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
pFieldinfo (PFIELDINFO) 
Pointer or error. 


0 Reserved value, 0. The WinGetLastError function may return the following 
errors: 


e PMERR_INSUFFICIENT_MEMORY 
e PMERR_INVALID PARAMETERS. 


Other If the nFieldinfo parameter has a value of 1, a pointer to a FIELDINFO data 
structure is returned. 


A pointer to the first FIELDINFO structure in a linked list of FIELDINFO 
structures is returned if the nFieldinfo parameter has a value greater than 1. 
The pointer to the next FIELDINFO structure is set in each pNextFieldinfo field 
of the FIELDINFO data structure. The last pointer is set to NULL. 
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Remarks 
The container contro! requires that the application use the CM_ALLOCDETAILFIELDINFO 
message to allocate memory for any FIELDINFO structures that are used. 


Default Processing | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 


CM_ALLOCRECORD 


This message allocates memory for one or more RECORDCORE structures. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data 
structures and messages. 


Parameters 
param1 


cbRecordData (ULONG) 
Bytes of additional memory. 


The number of bytes of additional memory that you want to reserve for your 
application’s private use. This parameter must have a value between 0 and 64,000. 
If the value is 0, no additional memory is allocated, but a RECORDCORE data 
structure is allocated. 


param2 


nRecords (USHORT) 
Number of records. 


The number of container records to be allocated. This parameter must have a 
value greater than 0. 
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Returns 
pRecord (PRECORDCORE) 
Returns a pointer or an error. 


NULL Allocation failed. The WinGetLastError function may return the following errors: 


e PMERR_INSUFFICIENT MEMORY 
¢ PMERR_INVALID_PARAMETERS. 


Other _ If the nRecords parameter has a value of 1, a pointer to a RECORDCORE 
structure is returned. 


If the nRecords parameter has a value greater than 1, a pointer to the first 
RECORDCORE structure in the linked list of records is returned. The pointer to 
the next container record is set in the preccNextRecord field in each 
RECORDCORE data structure. The last pointer is set to NULL. 


Remarks 
The container control requires that the application use the CM_ALLOCRECORD message to 
allocate memory for container records. 


When a record is allocated, the cb field of the record will be initialized with the size of the 
record structure type currently in use, either RECORDCORE or MINIRECORDCORE. if the 
CCS_MINIRECORDCORE style bit is not specified, the record is allocated according to the 
size of the RECORDCORE data structure. However, if the CCS_MINIRECORDCORE style 
bit is specified, the record is allocated according to the size of the MINIRECORDCORE data 
structure. This size should not be modified by the application. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 
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CM_ARRANGE 


This message arranges the container records in the icon view of the container control. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE __Icon/text or bit-map/text pairs were successfully arranged. 
FALSE An error occurred. 


Remarks 3 

The container items fill the topmost row until the width of the client area is reached. The 
container items then wrap to form another row immediately below the filled row. This 
process is repeated until all of the container items are positioned in rows. Default spacing is 
implemented according to the guidelines for the CUA user interface. A vertical scroll bar is 
enabled, if necessary. 


Before the relocation of the container items, the origin of the client area rectangle is reset to 
coincide with the origin of the container’s workspace. Arranging the container items does not 
affect the record attributes. 


If the CCS_AUTOPOSITION style bit is set, you do not need to send the CM_ARRANGE 
message, since this style bit causes the container control to arrange the container items for 
the application. 


If the current view is not the icon view, no visible change occurs until the current view is 
switched to the icon view. For example, if the name view is the current view and the 
CM_ARRANGE message is sent, the display does not change. 


The container updates the pilicon field of the RECORDCORE structure with the new 
coordinates. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes _ 
no action on it other than to return FALSE. 
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CM_CLOSEEDIT 


This message closes the window that contains the multiple-line entry (MLE) field used to edit 
container text directly. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE _ The direct editing of container item text was successfully ended. 
FALSE The direct editing of container item text was not successfully ended. The 
WinGetLastError function may return the following error: 


PMERR_INSUFFICIENT_MEMORY. 


Remarks 

The application sends this message to the container control to end the direct editing of 
container text. The application can assign this message to a key or key combination, a 
menu choice, or both so that the user can end the direct editing of container text from the 
keyboard. 


When the container control receives this message, it sends the CN_REALLOCPSZ and 
CN_ENDEDIT notification codes to the application. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_COLLAPSETREE 


This message causes one parent item in the tree view to be collapsed. 


Parameters 
param1 


pRecord (PRECORDCORE) . 
Pointer to the RECORDCORE structure that is to be collapsed. 


If this is NULL, all expanded parent items are collapsed. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE _ The item was successfully collapsed. 
FALSE An error occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_PARAMETERS. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_ERASERECORD 


This message erases the source record from the current view when a move occurs as a 
result of direct manipulation. 


Parameters 
param1 


pRecord (PRECORDCORE) 
Pointer to the container record that is to be erased from the current view. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE _ The record was successfully erased. 
FALSE The record was not erased. The WinGetLastError function may return the 
following errors: 
e PMERR_INVALID_PARAMETERS 
e PMERR_INSUFFICIENT_MEMORY. 


Remarks 
The container record is not removed and memory is not freed; only the visual appearance is 
changed. The visibility flag associated with the container record is not changed. 


Default Processing 


The default window procedure does not expect to receive this messagé and therefore takes 
no action on it other than to return FALSE. 
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CM_EXPANDTREE 


This message causes one parent item in the tree view to be sipanded| 


Parameters 
param1 


pRecord (PRECORDCORE) 
Pointer to the RECORDCORE structure that is to be expanded. 


If this is NULL, all collapsed parent items are expanded. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 
TRUE _ The item was successfully expanded. 


FALSE Anerror occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_ PARAMETERS. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_FILTER 


This message filters the contents of a container so that a subset of the container items is 
viewable. 


Parameters: 
param1 


pfnFilter (PFN) 
Pointer to an application-supplied filter function. 


param2 


pStorage (PVOID) 
Application use. 


Available for application use. 


Returns 
re (BOOL) 
Success indicator. 


TRUE _ A subset was successfully created. 


FALSE An error occurred. The WinGetLastError function may return the following 
errors: 


¢ PMERR_NO FILTERED ITEMS 
¢ PMERR_INSUFFICIENT_MEMORY. 


Remarks 
Filtering is enabled by setting the CRA_FILTERED attribute of container records that are to 
be excluded from the viewable subset. 


The pfnFilter parameter points to an application-provided function that determines whether a 
record is to be included in the viewable subset. The pfnFilter parameter must be declared 
as: . 


BOOL PFN pfnFilter (PRECORDCORE p, PVOID pStorage) ; 


where p points to a RECORDCORE structure that describes the container record to be 
tested. The pfnFilter parameter returns TRUE if the record is to be included in the viewable 
subset, or FALSE if it is to be excluded. The container sets the CRA_FILTERED attribute for 
the record based on the return from the pfnFi/ter parameter. 


Note: If the CCS _MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 
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If the CRA_FILTERED attribute is set for the record, the record is not visible. {f the 
CCS_AUTOPOSITION style bit is set and the container is showing the icon view, the 
container records are arranged when a record is filtered out. 


The CM_FILTER message supports only one level of filtering. 


It is the application’s responsibility to provide a National Language Support-enabled 
(NLS-enabled) function for the pfnFilter parameter. 


If the pfnFilter parameter value is NULL, a container is returned to an unfiltered state. If 
functions such as inserting a record into a container, arranging the records, or sorting the 
records are performed on a container whose records have been filtered, the effect of these 
functions remains if the container records are later unfiltered. 


All messages act on the entire container. For example, a record that is filtered and is 
removed from the container will be removed from the container entirely; it is not present in 
the container when the container records are unfiltered. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_FREEDETAILFIELDINFO 


This message frees the memory associated with one or more FIELDINFO structures. 


Parameters 
param1 


pFieldInfoArray (PVOID) 
Pointer to an array of pointers to FIELDINFO structures that are to be freed. 


param2 
cNumFieldinfo (USHORT) 


Number of structures. 
Number of FIELDINFO structures to be freed. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Memory associated with a specified FIELDINFO structure or structures in the 
container was freed. 


FALSE Associated memory was not freed. The WinGetLastError function may return 
the following errors: 


* PMERR_INVALID PARAMETERS 
¢ PMERR_MEMORY_DEALLOCATION_ERR 
¢ PMERR_FI_CURRENTLY_INSERTED. 


Remarks 
It is the application’s responsibility to free all application-allocated memory associated with 
the structures, such as user data. 


If a specified FIELDINFO structure is currently inserted into the container, the structure is not 
freed and the PMERR_Fl_CURRENTLY_INSERTED error is set. FIELDINFO structures 
must be removed with the CM_REMOVEDETAILFIELDINFO message before the 
CM_FREEDETAILFIELDINFO message is used. 


If the number of pointers to FIELDINFO structures in the array exceeds the count of 
structures to be freed, only the number of structures in the cNumFieldinfo parameter is freed. 
If either the pFieldinfoArray or the cNumFieldinfo parameter is invalid, the 
PMERR_INVALID_PARAMETERS error is set and no FIELDINFO structures are freed. 


If the PMERR_MEMORY_DEALLOCATION_ERR error occurs, any further processing is 
unreliable. 


Default Processing , 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_FREERECORD 


This message frees the memory associated with one or more RECORDCORE structures. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pRecordArray (PVOID) 
Pointer to an array of pointers to RECORDCORE structures that are to be freed. 


param2 


cNumRecord (USHORT) 
Number of records. 


Number of container records to be freed. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Memory associated with a record or records in the container was freed. 


FALSE Associated memory was not freed. The WinGetLastError function may return 
the following errors: 


¢ PMERR_INVALID_ PARAMETERS 
* PMERR_MEMORY_DEALLOCATION_ ERR 
¢ PMERR_RECORD_CURRENTLY_INSERTED. 


Remarks 
It is the application’s responsibility to free all application-allocated memory associated with 
the container records, such as text strings. 


If a specified record is currently inserted into the container, the record is not freed and the 
PMERR_RECORD_CURRENTLY_INSERTED error is set. Container records must be 
removed with the CM_REMOVERECORD message before the CM_FREERECORD message 
is used. 


If the number of pointers to container records in the array exceeds the count of records to be 
freed, only the number of records in the cNumRecord parameter is freed. If either the 
pRecordArray or the cNumRecord parameter is invalid, the 
PMERR_INVALID_PARAMETERS error is set and no container records are freed. 
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If the PMERR_MEMORY_DEALLOCATION_ERR error occurs, any further processing is 
unreliable. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_HORZSCROLLSPLITWINDOW 


This message scrolls a split window in the split details view. 


Parameters 
param1 


usWindow (USHORT) 
Window indicator. 


CMA_LEFT The left split window is scrolled. 
CMA_RIGHT _ The right split window is scrolled. 


param2 


IScrolllInc (LONG) 
Amount to scroll. 


Amount (in pixels) by which to scroll the window. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE An error occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_- PARAMETERS. 


Remarks 

The /Scrollinc parameter indicates a change in position. If the /Scrollinc parameter value is 
greater than 0, the window specified in the usWindow parameter is scrolled to the right by 
the number of pixels specified in the /Scrollinc parameter. If the value of the /Scrollinc 
parameter is less than 0, the window specified in the usWindow parameter is scrolled to the 
left by the number of pixels specified in the /Scrollinc parameter. This message is used to 
scroll either the left or right split window by an absolute amount. 


The columns that are to appear in each split window are determined at the time the split 
window is created. Thereafter, columns in the left split window cannot be seen in the right 
split window, and vice versa. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_INSERTDETAILFIELDINFO 


This message inserts one or more FIELDINFO structures into a container control. 


Parameters 
param1 


pFieldinfo (PFIELDINFO) 
Pointer to the FIELDINFO structure or structures to insert. 


param2 


pFieldinfolnsert (PFIELDINFOINSERT) 
Pointer to the FIELDINFOINSERT data structure. 


See “FIELDINFOINSERT” on page A-75 for the descriptions of this structure’s fields 
as they apply to the CM_INSERTDETAILFIELDINFO message. 


Returns 
cFields (USHORT) 
Number of structures. 


0 The FIELDINFO structure or structures were not inserted. The WinGetLastError 
function may return the following errors: 


e PMERR_INVALID_PARAMETERS 
e PMERR_INSUFFICIENT_MEMORY 
e PMERR_FI_CURRENTLY_INSERTED. 


Other The number of FIELDINFO structures in the container. 


Remarks 

The pFieldinfoinsert parameter is used to insert FIELDINFO structures into the container. 
The pFieldinfoOrder field of the FIELDINFOINSERT data structure is used to place 
FIELDINFO structures into the container in order, relative to the other structures. Specifying 
the CMA_FIRST attribute places the FIELDINFO structure at the front of the list of structures. 
If the CMA_END aittribute is specified, the FIELDINFO structure is placed at the end of the — 
list of structures. Otherwise, if the value of the pFieldinfoOrder field is a pointer to a 
FIELDINFO structure, the structure being inserted is placed after this structure. 


If the value of the cFieldinfoinsert field of the FIELDINFOINSERT data structure is greater 
than 1, a linked list of FIELDINFO structures is inserted in the order specified by the 
pFieldinfoOrder field. Here, the pFieldinfo parameter points to the first of a linked list of 
FIELDINFO structures. This list of structures is linked together as they were when the 
FIELDINFO structures were allocated. 
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If one FIELDINFO structure is to be inserted, the cFieldinfolnsert field has a value of 1 and 
the pFieldinfo parameter points to the FIELDINFO structure to be inserted. 


After the FIELDINFO structures have been inserted, if the flnvalidateFieldinfo field of the 
FIELDINFOINSERT data structure is FALSE, the CM_INVALIDATEDETAILFIELDINFO 
message must be sent to update the display with the inserted structures. 


If the CCS_VERIFYPOINTERS style bit is set and the pFieldinfo parameter contains a 
pointer to a FIELDINFO structure that is currently inserted, the 
PMERR_Fl_CURRENTLY_INSERTED error is set and no FIELDINFO structures are 
inserted. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


CM_INSERTRECORD 


This message inserts one or more RECORDCORE structures into a container control. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pRecord (PRECORDCORE) 
Pointer to the RECORDCORE structure or structures to insert. 


param2 


pRecordinsert (PRECORDINSERT) 
Pointer to the RECORDINSERT data structure. 


See “RECORDINSERT” on page A-177 for definitions of this structure’s fields as 
they apply to the CM_INSERTRECORD message. 
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Returns 
cRecords (ULONG) 
Number of structures. 


0 The RECORDCORE structure was not inserted. The WinGetLastError function 
may return the following errors: 


¢ PMERR_INVALID PARAMETERS 
¢ PMERR_INSUFFICIENT_ MEMORY 
¢ PMERR_RECORD_CURRENTLY_INSERTED. 


Other The number of RECORDCORE structures in the container. 


Remarks | 

The pRecordinsert parameter is used to insert. RECORDCORE structures into the container. 
The pRecordOrder and pRecordParent fields of the RECORDINSERT data structure are 
used to place each record into the container in order, relative to the other records. If the 
CMA_FIRST or CMA_END attributes are specified, records are inserted before the first child 
or after the last child of the record specified in the pRecordParent field. If the value of the 
pRecordParent field is NULL, the record or records are inserted before the first record or 
after the last record, respectively, at the root level. Otherwise, if the value of the 
pRecordOrder field is a pointer to a record, the record or records to be inserted are placed 
after this record. 


A z-ordering of the records is maintained by the container control. The zOrder field of the 
RECORDINSERT data structure is used to specify the record’s z-order in the container, 
relative to the other records. The CMA_TOP attribute is used to place the record at the end 
of the z-order list, while the CMA_BOTTOM attribute places the record at the beginning of 
the z-order list. Z-ordering is used for the icon view only. 


If the value of the cRecordsinsert field of the RECORDINSERT data structure is greater than 
1, a linked list of RECORDCORE structures is inserted in the order specified by the 
pRecordOrder, pRecordParent, and zOrder fields. Here, the pRecord parameter points to 
the first RECORDCORE structure of a linked list of structures. 


If one RECORDCORE structure is to be inserted, the cRecordsinsert field has a value of 1 
and the pRecord parameter points to the RECORDCORE structure to be inserted. 


When containers display the icon view, the coordinates specified by the RECORDCORE 
structure’s ptiicon field are used to position inserted container records in the container’s 
workspace. If the coordinates are not specified and the CCS_AUTOPOSITION style bit is 
not set, all of the inserted container records are positioned at (0,0) and a CM_ARRANGE 
message must be sent to position them elsewhere. If the CCS_AUTOPOSITION style bit is 
set, the container records are positioned without the CM_ARRANGE message being sent. 


After the container records have been inserted: 


e lf the flnvalidateRecord field of the RECORDINSERT data structure is FALSE, the 
CM_INVALIDATERECORD message must be sent to update the display with the 
inserted records. If the current view is the icon view and either the 
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CCS_AUTOPOSITION style bit is set or the flnvalidateRecord field is TRUE, the view is 
updated without the CM_INVALIDATERECORD message being sent. 


¢ The preccNextRecord, flRecordAttr, and ptlicon fields of the external RECORDCORE 
structure are not updated as changes occur within the container. However, if records 
are shared among multiple containers, the fiRecordAttr and pilicon fields are modified 
internally. Refer to the OS/2 2.00 Programming Guide for more information about the 
modification of these fields. 


If the CCS_VERIFYPOINTERS style bit is set and the pRecord parameter contains a pointer 
to a RECORDCORE structure that is currently inserted, the 
PMERR_RECORD_CURRENTLY_INSERTED error is set and no RECORDCORE structures 
are inserted. 


If the RECORDCORE structures are sorted on insertion, the pRecordOrder and zOrder fields 
-are ignored. 


Default Processing . 
The default window procedure does not expect to receive this message and therefore takes © 
no action on it other than to return 0. 


CM_INSERTRECORDARRAY 


This message inserts one or more RECORDCORE structures into a container control. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container control is 
created, then MINIRECORDCORE should be used instead of RECORDCORE, and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pRecordArray (PVOID) | 
Pointer to an array of pointers to RECORDCORE structures that are to be inserted 
into the container. 


param2 


pRecordinsert (PRECORDINSERT) 
Pointer to the RECORDINSERT structure. 
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‘Returns 
cRecords (ULONG) 
Number of RECORDCORE structures in the root level of the container. 


0 No RECORDCORE structures were inserted. 
The WinGetLastError function may return the following errors: 


PMERR_INVALID_ PARAMETERS 
PMERR_INSUFFICIENT_ MEMORY 
PMERR_RECORD_CURRENTLY_INSERTED 


Other The number of RECORDCORE structures in the container. 


Remarks 

The pRecordinsert parameter is used to insert RECORDCORE structures into the container. 
The pRecordOrder and pRecordParent fields of the RECORDINSERT data structure are 
used to place each record into the container in order, relative to the other records. If the 
CMA_FIRST or CMA_END attributes are specified, records are inserted before the first child 
or after the last child of the record specified in the pRecordParent field. If the value of the 
pRecordParent field is NULL, the record or records are inserted before the first record or 
after the last record, respectively, at the root level. Otherwise, if the value of the 
pRecordOrder field is a pointer to a record, the record or records to be inserted are placed 
after this record. 


A z-ordering of the records is maintained by the container control. The zOrder field of the 
RECORDINSERT data structure is used to specify the record’s z-order in the container, 
relative to the other records. The CMA_TOP attribute is used to place the record at the end 
of the z-order list, while the CMA_BOTTOM attribute places the record at the beginning of 
the z-order list. Z-ordering is used for the icon view only. 


The cRecords parameter always specifies an array of pointers to RECORDCORE structures 
to. be inserted into the container. The number of pointers contained in the array must equal 
the value specified in the cRecordsinsert field of the RECORDINSERT structure. 


When containers display the icon view, the coordinates specified by the RECORDCORE 
structure’s pilicon field are used to position inserted container records in the container’s 
workspace. lf the coordinates are not specified and the CCS_AUTOPOSITION style bit is 
not set, all of the inserted container records are positioned at (0,0) and a CM_ARRANGE 
message must be sent to position them elsewhere. If the CCS_AUTOPOSITION style bit is 
set, the container records are positioned without the CM_ARRANGE message being sent. 
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After the container records have been inserted: 


e If the finvalidateRecord field of the RECORDINSERT data structure is FALSE, the 
CM_INVALIDATERECORD message must be sent to update the display with the 
inserted records. If the current view is the icon view and either the 
CCS_AUTOPOSITION style bit is set or the finvalidateRecord field is TRUE, the view is 
updated without the CM_INVALIDATERECORD message being sent. 


e¢ The preccNextRecord, fiRecordAttr, and ptilcon fields of the external RECORDCORE 
structure are not updated as changes occur within the container. However, if records 
are shared among multiple containers, the flRecordAttr and ptllcon fields are modified 
internally. 


If the CCS_VERIFYPOINTERS style bit is set and the pRecordArray parameter contains a 
pointer to a RECORDCORE structure that is currently inserted, the 
PMERR_RECORD_CURRENTLY_INSERTED error is set and no RECORDCORE structures 
are inserted. 


lf the RECORDCORE structures are sorted on insertion, the pRecordOrder and zOrder fields 
are ignored. 


Default Processing 
The default window procedure does not expect to receive this message and, therefore, takes 
no action on it other than to return FALSE. 


CM_INVALIDATEDETAILFIELDINFO 


This message notifies the container control that any or all FIELDINFO structures are not valid 
and that the view must be refreshed. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE FIELDINFO structures were successfully refreshed. 
FALSE FIELDINFO structures were not successfully refreshed. 
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Remarks 

If any or all FIELDINFO structures are shangee: removed, or inserted, the 
CM_INVALIDATEDETAILFIELDINFO message must be sent. Since each FIELDINFO 
structure potentially affects every record in the container, the entire view is refreshed, even if 
only one FIELDINFO structure has changed. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_INVALIDATERECORD 
"This message notifies the container control that a RECORDCORE structure or structures are 
not valid and must be refreshed. 


Note: If the CCS _MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pRecordArray (PVOID) 
Pointer to an array of pointers to RECORDCORE structures that are to be 
refreshed. 


param2 | 


cNumRecord (USHORT) 
Number of container records to be refreshed. 


If the cNumRecord parameter has a value of 0, all of the records in the container 
are refreshed and the pRecordArray parameter is ignored. 


flnvalidateRecord (USHORT) 
Flags used to optimize container record invalidation. 


The CMA_REPOSITION, CMA_NOREPOSITION, and CMA_TEXTCHANGED 
attributes are mutually exclusive. However, any of them can be combined with the 
CMA_ERASE attribute by using a logical OR operator ((). 


CMA_ERASE Flag used when the icon view is displayed to minimize 
painting of a container record’s background when it has 
changed. If specified, the background is erased when the 
display is refreshed. The default is to not erase the 
background when the display is. refreshed. 
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CMA_REPOSITION 


CMA_NOREPOSITION 


CMA_TEXTCHANGED 


Returns 
re (BOOL) 
Success indicator. 


Flag used to reposition all container records. This flag 
must be used if container records are inserted or 
removed, or if many changes have occurred. Ifa 
container record is inserted, the pRecordArray parameter 
points to the inserted record. If a container record is 
removed, the pRecordArray parameter points to the 
record that precedes the removed one. If several 
container records have changed, an array of container 
record pointers must be used. The container determines 
the first record to be invalidated. This is the default. 


Flag used to indicate that container records do not need 
to be repositioned. The container draws the record or 
records pointed to in the pRecordArray parameter. The 
container does not do any validation; therefore it is the 
application’s responsibility to make sure repositioning is 
not needed or changing the longest text line is not 
necessary. 


Flag used if text has changed and you do not know 
whether repositioning is needed. The container 
determines whether the longest line or the height of the 
record has changed. If so, the container repositions and 
redraws the necessary visible container records. 


It may be necessary to reposition the container records if 
the number of lines of text has changed. Warning: The 
application must send a CM_INVALIDATERECORD 
message if text changes. Otherwise, any further 
processing is unreliable. 


TRUE Records were successfully refreshed. 


FALSE An error occurred. The WinGetLastError function may return the following 


errors: 


¢ PMERR_INVALID_PARAMETERS 
¢ PMERR_INSUFFICIENT_ MEMORY. 


Remarks 


If the number of pointers to container records in the array exceeds the count of records to be 
refreshed, only the number of records specified in the cNumRecord parameter is refreshed. 
If the CCS_VERIFYPOINTERS style bit is set and the pRecordArray parameter contains 
pointers to a RECORDCORE structure or structures that do not exist, the 
PMERR_INVALID_PARAMETERS error is set and nothing is refreshed. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_MOVETREE 


This message is used to move a record to a new parent in the container control. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container control is 
created, then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pTreeMove (PTREEMOVE) 
Pointer to a TREEMOVE structure. 


See TREEMOVE for definitions of this structure's fields as they apply to the 
CM _MOVETREE message. 


param2 


Reserved (ULONG) 
Reserved value, must be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Record and associated subtrees were moved successfully. 
FALSE _ Error occurred, and tree structure remains unchanged. 


Remarks 

This message is used to change the parent of a record in the container control. The fields of 
the TREEMOVE structure describe the record to be moved, the record to become its new 
parent, and where to insert the record relative to other records with the same parent. 


If the preccNewParent field of the TREEMOVE structure is NULL, the record being moved is 
moved to the root level; otherwise, it is moved to preccNewParent. The pRecordOrder field 
of the TREEMOVE structure determines where the record being moved is placed relative to 
other records with the same parent (the one specified by preccNewParent). If fiMoveSiblings 
of the TREEMOVE structure is TRUE, all siblings that follow the record being moved 
(preccMove) are moved to the new parent as well. Siblings that precede preccMove are not 
moved regardless of the value of the fiMoveSiblings field. For normal Tree Move operations, 
the flMoveSiblings field of the TREEMOVE structure should be set to FALSE. 
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WinGetLastError returns PMERR_INVALID_PARAMETERS if any of the following illegal 
combinations are used: 


¢ fiMoveSiblings is either the first or last root level record in the container, and the 
fiMoveSiblings flag is TRUE. 


e preccMove is a root level record, and preccNewParent is currently one of its children. 


e pRecordOrder is a pointer to a RECORDCORE structure (not CMA_FIRST or 
(CMA_LAST) tha does not exist in the list of children of the new. parent. 


e preccNewParent is NULL, and pRecordOrder is not a root level record. 


For example, the following tree contains two parents, each with three children: 
Parent A 


Child Al 
Child A2 
Child A3 


TIT 


Parent B 
Child Bl 
Child B2 


TT 


Child B3 


If preccMove is Child A2, preccNewParent is Parent B, pRecordOrder = CMA_LAST and 
fiMoveSiblings = TRUE, after the Tree Move operation, the new tree structure is as follows: 


Parent A 
-——arn Al 
Parent B 
Child Bl 
Child B2 
Child B3 
Child A2 
Child A3 


Default Processing 
The default window procedure does not expect to receive this message and, therefore, takes 
no action on it other than to return FALSE. 
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CM_OPENEDIT 


This message opens the window that contains the multiple-line entry (MLE) field used to edit 
container text directly. 


Parameters 
param1 


pCnrEditData (PCNREDITDATA) 
Pointer to the CNREDITDATA structure. 


See “CNREDITDATA’ on page A-29 for definitions of this structure’s fields as they 
apply to the CM_OPENEDIT message. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Direct editing of container text was successfully started. 
FALSE Direct editing of container text was not successfully started. The 
WinGetLastError function may return the following error: 


PMERR_INVALID_PARAMETERS. 


Remarks 

The application sends this message to the container control to start the direct editing of 
container text. The application can assign this message to a key or key combination, a 
menu choice, or both so that the user can start editing container text directly from the 
keyboard. 


When the container control receives this message, it sends the CN_BEGINEDIT notification 
code to the application. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_PAINTBACKGROUND 
This message informs an application whenever a container’s background is painted if the 
CA_OWNERPAINTBACKGROUND attribute of the CNRINFO data structure is specified. 


Parameters 
param1 


pOwnerBackground (POWNERBACKGROUND) 
Pointer to the OWNERBACKGROUND structure. 


See “OWNERBACKGROUND?” on page A-135 for definitions of this structure’s fields 
as they apply to the CM_PAINTBACKGROUND message. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Process indicator. 


TRUE The application processed the CM_PAINTBACKGROUND message. 
FALSE The application did not process the CM_PAINTBACKGROUND message. 


Remarks 

The CM_PAINTBACKGROUND message is provided so that an application can subclass the 
container control and paint its own background. If the application does not subclass the 
container control or subclasses the container control and returns FALSE, the container uses 
the system window color, which is specified by SYSCLR_WINDOW. This color can be 
changed by using the PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX 
presentation parameter of the WM_PRESPARAMCHANGED (in Container Controls) 
message. 


Default Processing | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_QUERYCNRINFO 


This message returns the container’s CNRINFO structure. 


Parameters 
param1 


pCnrinfo (PCNRINFO) 
Pointer to a buffer into which the CNRINFO structure is copied. 


param2 


cbBuffer (USHORT) 
Number of bytes. 


Maximum number of bytes to copy. 


Returns 
cbBytes (USHORT) 
Success indicator. 


0 Container data was not successfully returned. The WinGetLastError function 
may return the following error: 


PMERR_INVALID_PARAMETERS. 
Other Actual number of bytes copied. 


Remarks 
The number of bytes specified in the cbBuffer parameter is returned in the buffer addressed 
by the pCnrinfo parameter. 


Default Processing 
The default window procedure does not expect to receive this message and mierelore takes 
no action on it other than to return 0. 


CM_QUERYDETAILFIELDINFO 


This message returns a pointer to the requested FIELDINFO structure. 


Parameters 
param 


pfidinfoBase (PFIELDINFO) 


Pointer to the FIELDINFO structure used to search for the next or previous column. 
If the CMA_FIRST or CMA_LAST attribute is specified, this is ignored. 
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param2 


cmd (USHORT) 
Command that indicates which FIELDINFO structure to retrieve. 


CMA_FIRST _ First column in the container. 
CMA_LAST Last column in the container. 
CMA_NEXT Next column in the container. 
CMA_PREV _ Previous column in the container. 


Returns 
pFieldinfo (PFIELDINFO) 
Pointer to the FIELDINFO structure for which data was requested. 


NULL No FIELDINFO structures to retrieve. 


~1 The data from the FIELDINFO structure was not returned. The WinGetLastError 
function may return the following error: 


PMERR_INVALID_PARAMETERS. 
Other Pointer to the FIELDINFO structure for which data was requested. 


Remarks : 

If the cmd parameter has the value of the CMA_FIRST or CMA_LAST attribute, the 
pfidinfoBase parameter is ignored and the first or last column data, respectively, is returned. 
If the CMA_NEXT or the CMA_PREV attribute is set in the cmd parameter, the column data 
next to or before the column pointed to by the pFieldinfo parameter is returned. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 


CM_QUERYDRAGIMAGE 


This message returns a handle to the icon or bit map for the record in the current view. 


Parameters 
param1 


pRecord (PRECORDCORE) . 
Pointer to the RECORDCORE structure that is to be queried for the image. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 


himage (LHANDLE) 
Image handle. 
NULLHANDLE _ If no image is defined, NULLHANDLE is returned. 
Other Handle of an icon or bit map. 

_¢ If the CA_DRAWICON attribute and the CV_MINI style bit are 
specified, the RECORDCORE structure’s hptrMinilcon field is 
returned. 

¢ If the CA_DRAWICON attribute is specified without the CV_MINI 
style bit, the RECORDCORE structure’s Aptricon field is returned. 

e {f the CA_DRAWBITMAP attribute and the CV_MINI style bit are 
specified, the RECORDCORE structure’s hbmMiniBitmap field is 
returned. 

e lf the CA_DRAWBITMAP attribute is specified without the 
CV_MINI style bit, the RECORDCORE structure’s hbmBitmap field 
is returned. . 

Remarks 


If the CCS_MINIRECORDCORE style bit is specified, this function will always return the 
MINIRECORDCORE structure’s hptricon field. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULLHANDLE. 
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CM_QUERYRECORD 


This message returns a pointer to the requested RECORDCORE structure. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pRecord (PRECORDCORE) 
Pointer to the RECORDCORE structure used to search for the next or previous 


container record. 


If the CMA_FIRST or CMA _LAST attribute is specified, this is ignored. 


param2 


cmd (USHORT) 


Command that indicates which container record to retrieve: 


CMA_FIRST 
CMA_FIRSTCHILD 
CMA_LAST 
CMA_LASTCHILD 
CMA_NEXT 
CMA_PARENT 
CMA_PREV 


fsSearch (USHORT) 
Enumeration order. 


First record in the container. 

First child record of pRecord specified in param7. 
Last record in the container. 

Last child record of pRecord specified in param7. 
Next record of pRecord specified in param1. 
Parent of pRecord specified in param7. 

Previous record of pRecord specified in param7. 


Specifies the enumeration order. This value is one of the following: 


CMA_ITEMORDER 
CMA_ZORDER 


Container records are enumerated in item order, first to last. 


Container records are enumerated by z-order, from first 
record in the z-order to the last record. The last z-order 
record is the last record to be drawn. This flag is valid for 
the icon view only. 
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Returns 

pRecord (PRECORDCORE) 
Pointer to the RECORDCORE structure for which data was requested. 
NULL No RECORDCORE structures to retrieve. 


-1 The container record data was not returned. The WinGetLastError function may 
return the following error: 


PMERR_INVALID_- PARAMETERS. 


Other Pointer to the container record for which data was requested. 


Remarks 
If the cmd parameter has the value of CMA_FIRST or CMA_LAST, the pRecord parameter in 
param1 is ignored and the first or last record, respectively, in the container is returned. 


Depending on the value of the fsSearch parameter, the container records are enumerated in 
item order or in z-order. 


See “RECORDCORE?” on page A-175 or “MINIRECORDCORE” on page A-124 for a 
complete list and descriptions of all container record attributes. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 


CM_QUERYRECORDEMPHASIS 


This message queries for a container record with the specified emphasis attributes. 


Parameters 
parami 


pSearchAfter (PRECORDCORE) 
Pointer to the specified container record. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


The values of this parameter can be: 


CM_FIRST Start the search with the first record in the container. 
Other Start the search after the record specified by this pointer. 
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param2 


fEmphasisMask (USHORT) 
Emphasis attribute. 


Specifies the emphasis attribute of the container record. The following states can 
be combined using a logical OR operator (|): 


CRA_COLLAPSED Specifies that a record is collapsed. 
CRA_CURSORED Specifies that a record will be drawn with a selection 


cursor. 

CRA_DISABLED Specifies that a record will be drawn with unavailable-state 
emphasis. 

CRA_DROPONABLE _ Specifies that a record can be a target for direct 
manipulation. 

CRA_EXPANDED Specifies that a record is expanded. 

CRA_FILTERED Specifies that a record is filtered and, therefore, hidden 
from view. 

CRA_INUSE Specifies that a record will be drawn with in-use emphasis. 

CRA_PICKED Specifies that the container record willl be picked up as part 
of the drag set. 

CRA_SELECTED Specifies that a record will be drawn with selected-state 
emphasis. 

CRA_SOURCE Specifies that a record will be drawn with source-menu 
emphasis. 


Returns 
pRecord (PRECORDCORE) 
Pointer to the record with the specified emphasis. 


NULL This implies that none of the records that follow the pointer specified in the 
pSearchAfter parameter meet those specifications. 
-1 The container record data was not returned. 
| The WinGetLastError function may return the following error: 
PMERR_INVALID_PARAMETERS (1208) 
Other Pointer to a container record with the specified emphasis. 


This is the first record that follows the record pointed to by the pSearchAfter 
parameter and satisfies the criteria specified in the fEmphasisMask parameter. To 
find the next record that satisfies this criteria, send this message again, but this 
time use the value returned in the pRecord parameter for the value of the 
pSearchAfter parameter. 


Default Processing | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 
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CM_QUERYRECORDFROMRECT 


This message queries for a container record that is bounded by the specified rectangle. 


Parameters 
param1 


pSearchAfter (PRECORDCORE) 
Pointer to the specified container record. 


To get all the container records within the specified rectangle, this message is sent 
repeatedly, each time.this parameter is set to. the pointer that is returned by the 
previous usage of this message. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


The values of this parameter can be: 


CMA_FIRST _ Start the search with the first record in the container. 
Other Start the search after the record specified by this pointer. 


param2 


pQueryRecFromRect (PQUERYRECFROMRECT) 
Pointer to the QUERYRECFROMRECT data structure. 


See “QUERYRECFROMRECT” on page A-173 for definitions of this structure’s 
fields as they apply to the CM_ QUERYRECORDFROMRECT message. 


Returns 
pRecord (PRECORDCORE) 
Pointer to the container records within the bounding rectangle. 


NULL No container records are within the bounding rectangle. 


-1 The container record data was not returned. The WinGetLastError function may 
return the following error: 


PMERR_INVALID_PARAMETERS. 


Other Pointer to the container record within the bounding rectangle. 
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Remarks 
This message returns the pointer to the first container record found in the rectangle after the 
starting position specified in the pSearchAfter parameter. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 


CM_QUERYRECORDINFO 


This message updates the specified records with the current information for the container. 


Parameters 
param1 


pRecordArray (PVOID) 
Pointer to an array of pointers to RECORDCORE structures to which the current 
information is to be copied. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should should be used instead of 


RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE all applicable data structures and messages. 


param2 


cNumRecord (USHORT) 
Number of records. 


The number of container records to be updated. If the cNumRecord parameter has 
a value of 0, all of the records in the container are updated and the pRecordArray 
parameter is ignored. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Record information was successfully updated. 
FALSE An error occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_PARAMETERS. 


Remarks . 
This message is needed only if the application is sharing records among multiple containers 
in the same process. 
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The flRecordAttr and pilicon fields are updated internally when they change, but not in the 
external RECORDCORE structure. Therefore, the application’s external record does not 
always have current information in these fields. This message is only needed if the 
application is sharing records among multiple containers in the same process. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_QUERYRECORDRECT 


This message returns the rectangle of the specified container record, relative to the container 
window origin. 


Parameters 
param1 


prelitem (PRECTL) 
Pointer to the RECTL structure, into which the rectangular coordinates are placed. 


param2 


pQueryRecordRect (PQUERYRECORDRECT) 
Pointer to the QUERYRECORDRECT structure. 


See “QUERYRECORDRECT” on page A-174 for definitions of this structure’s fields 
as they apply to the CM_QUERYRECORDRECT message. 


Returns 
re (BOOL) 
Success indicator. 


TRUE A rectangle with valid coordinates is returned. 


FALSE _ The rectangle is not successfully returned. The WinGetLastError function may 
return the following error: 


PMERR_INVALID_ PARAMETERS. 


~ Remarks 
The coordinates of the returned rectangle are in window coordinates. 


If the input record is not found in the container, the output rectangle is empty. 


For a container using the details view (CV_DETAIL), all of the data for a row is returned in 
the rectangle. — . 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_QUERYVIEWPORTRECT 


This message returns a rectangle that contains the coordinates of the container’s client area. 
These are virtual coordinates that are relative to the origin of the coordinate space 
requested. 


Parameters 
param1 


prelViewport (PRECTL) 
Pointer to the RECTL structure. 


Pointer to the RECTL structure that the virtual coordinates of the client area 
rectangle are to be written into. 


param2 


usindicator (USHORT) 
Coordinate space indicator. 


One of the following must be used: 


CMA_WINDOW Returns the client area rectangle in container window 
coordinates. 


CMA_WORKSPACE _ Return the client area rectangle in coordinates relative to the 
origin of the container’s workspace. 


fRightSplitWindow (BOOL) 
Flag. 


Flag that specifies the right or left window in the split details view. This flag is 
ignored if the view is not the split details view. 


TRUE Right split window is returned. 
FALSE Left split window is returned. 
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Returns 
rc (BOOL) 
Success indicator. 


TRUE ~ The client area rectangle was returned successfully. 


FALSE Anerror occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_- PARAMETERS. 


Remarks 
The virtual coordinates of the client area rectangle are written into the structure addressed by 
the prcilViewport parameter. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_REMOVEDETAILFIELDINFO 


This message removes one, multiple, or all FIELDINFO structures from the container control. 


Parameters 
param1 


pFieldinfoArray (PVOID) 
Pointer to an array of pointers to FIELDINFO structures that are to be removed. 


param2 


cNumFieldinfo (USHORT) 
Number of FIELDINFO structures to be removed. 


If the cNumFieldinfo parameter has a value of 0, all of the FIELDINFO structures in 
the container are removed and the pFieldinfoArray parameter is ignored. 


fRemoveFieldinfo (USHORT) 


Flags. | 

Flags that show whether memory must be freed and FIELDINFO structures 
invalidated. 

CMA_FREE lf specified, FIELDINFO structures are removed and memory 


associated with the FIELDINFO structures is freed. If not 
specified, FIELDINFO structures are removed and no memory 
is freed; this is the default. 


22-66 PM Programming Reference Vol II 


CMA_INVALIDATE _ If specified, after FIELDINFO structures are removed, the 
container is invalidated, and any necessary repositioning of 
the FIELDINFO structures is performed. If not specified, 
invalidation is not performed. 


Returns 
cFields (SHORT) 
Number of structures. 


-1  Anerror occurred. The WinGetLastError function may return the following errors: 


¢ PMERR_INVALID PARAMETERS 
¢ PMERR_MEMORY_DEALLOCATION ERR. 


Other The number of FIELDINFO structures that remain in the container. 


Remarks 
The FIELDINFO structures are removed from the list of columns inserted into the container 
control. 


If the CMA_FREE attribute is not specified, the container control removes the specified 
FIELDINFO structures without freeing the memory. The application is responsible for freeing 
the memory associated with the FIELDINFO structures by using the 
CM_FREEDETAILFIELDINFO message. 


If the cNumFieldinfo parameter has a value of 0 and the CMA_FREE attribute is specified, all 
of the FIELDINFO structures in the container control are removed and the memory 
associated with the FIELDINFO structures is freed. It is the application’s responsibility to 
free all of the application-allocated memory associated with the FIELDINFO structures. 


If the number of pointers to FIELDINFO structures in the array exceeds the count of 
FIELDINFO structures to be removed, only the number of structures specified in the 
cNumFieldinfo parameter are removed. If the CCS_VERIFYPOINTERS style bit is set and 
the pFieldinfoArray parameter contains pointers to a FIELDINFO structure or structures that 
do not exist, the PMERR_INVALID_PARAMETERS error is set. 


If you do not want to show a column, you can hide it by setting the CFA_INVISIBLE attribute 
of the FIELDINFO data structure and notifying the container control with the 
CM_INVALIDATEDETAILFIELDINFO message. 


If the CMA_INVALIDATE attribute is specified, the container is repainted. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes ~ 
no action on it other than to return0. 
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CM _REMOVERECORD 
This message removes one, multiple, or all RECORDCORE structures irom the container 
control. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, 
_ then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Parameters 
param1 


pRecordArray (PVOID) 
Pointer to an array of pointers to RECORDCORE structures that are to be removed. 


param2 


cNumRecord (USHORT) 
Number of records. 


Number of container records to be removed. If the cNumRecord parameter has a 
value of 0, all of the records in the container are removed and the pRecordArray 
parameter is ignored. 


fRemoveRecord (USHORT) 
Flags. 


Flags that show whether memory must be freed and container records invalidated. 


CMA_FREE If specified, RECORDCORE structures are removed and 
memory associated with the RECORDCORE structures is 
freed. If not specified, RECORDCORE structures are 
removed and no memory is freed; this is the default. 


CMA_INVALIDATE _ If specified, after RECORDCORE structures are removed the 
container is invalidated and any necessary repositioning of 
the container records is performed. If not specified, 
invalidation is not performed. 


This option is not valid in the icon view unless the 
CCS_AUTOPOSITION style bit is not set. In the icon view, 
the container record is refreshed if the CCS_AUTOPOSITION 
style bit is set. regardless of whether the CMA_INVALIDATE 
attribute is set. 
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Returns 
cRecords (LONG) 
Number of structures. 


-1  Anerror occurred. The WinGetLastError function may return the following errors: 


e PMERR_INVALID_PARAMETERS 
e PMERR_MEMORY_DEALLOCATION_ERR. 


Other Number of root level RECORDCORE structures that remain in the container. 


Remarks 
When parent item records are removed, all associated child item records are removed, as 
well. 


If the CMA_FREE attribute is not specified, the container control removes the specified 
RECORDCORE structures without freeing the memory. The application is responsible for 
freeing the memory associated with the RECORDCORE structure by using the 
CM_FREERECORD message. 


If the cNumRecord parameter has a value of 0 and the CMA_FREE attribute is specified, all 
of the RECORDCORE structures in the container control are removed and the memory 
associated with the RECORDCORE structures is freed. It is the application’s responsibility to 
free all of the application-allocated memory associated with the RECORDCORE structures. 


If the number of pointers to RECORDCORE structures in the array exceeds the count of 
RECORDCORE structures to be removed, only the number of records specified in the 
cNumRecord parameter is removed. If the CCS_VERIFYPOINTERS style bit is set and the 
pRecordArray parameter contains pointers to a RECORDCORE structure or structures that 
do not exist, the PMERR_INVALID_-PARAMETERS error is set. 


If the CMA_INVALIDATE attribute is specified, the container is repainted if the removed 
record or records are visible. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 
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CM_SCROLLWINDOW 


This message scrolls an entire container window. 


Parameters 
param1 


fsScrollDirection (USHORT) 
Scroll direction. 


Direction in which to scroll the container window. 


CMA_VERTICAL Scroll vertically. 
CMA_HORIZONTAL — Scroll horizontally. 


param2 


!Scrolllne (LONG) 
Scroll increment. 


Amount (in pixels) by which to scroll the window. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE — Successful completion 
FALSE An error occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_PARAMETERS. 


Remarks . 

If the /Scrollinc parameter value is greater than 0 and the CMA_HORIZONTAL attribute is 
specified, the container window is scrolled to the right. The container window is scrolled 
down if the /Scroilinc parameter value is greater than 0 and the CMA_VERTICAL attribute is 
specified. Similarly, the container window is scrolled left and up, respectively, if the /Scrollinc 
parameter value is less than 0 and the same two attributes are specified. 


If you want the container window to be scrolled by an amount that is indicated with a key, 
such as the PgUp, PgDn, Home, and End keys, the application can send a key event to the 
scroll bar. 


If the container window is displaying the split details view, the 
CM_HORZSCROLLSPLITWINDOW message is used for horizontal scrolling. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. . 
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CM_SEARCHSTRING 


This message returns the pointer to a container record whose text matches the string. 


Parameters 
param1 


pSearchString (PSEARCHSTRING) 
Pointer to the SEARCHSTRING structure. 


See “SEARCHSTRING’ on page A-184 for definitions of this structure’s fields as 
they apply to the CM_SEARCHSTRING message. 


param2 


pSearchAfter (PRECORDCORE) 
Pointer to the starting container record. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


CMA_FIRST Start the search at the first container record. 


Other Start the search after the container record specified by this pointer. 
To get all of the records in the container whose text matches the 
string, this message is sent repeatedly. Each time this message is 
sent, the pSearchAfter parameter contains a pointer to the last 
record that was found. 


Returns 
pRecord (PRECORDCORE) 
Pointer to the found container record. 


NULL No container record’s text matches the search string. 

-1  Anerror occurred. The WinGetLastError function may return the following error: 
PMERR_INVALID- PARAMETERS. 

Other Pointer to the container record whose text matches the search string. 


Remarks 
The CM_SEARCHSTRING message is NLS-enabled. 


In the details view, the string is searched for in each column of each record. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULL. 
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CM_SETCNRINFO 


This message sets or changes the data for the container control. 


Parameters 
param1 


pCnrinfo (PCNRINFO) 
Pointer to the CNRINFO structure from which to set the data for the container. 


param2 


ulCnrinfoFl (ULONG) 
Flags. 


Flags that show which fields are to be set. 


CMA_PSORTRECORD Pointer to the comparison function for sorting 
- container records. If NULL, which is the default 

condition, no sorting is performed. Sorting only 
occurs during record insertion and when 
changing the value of this field. The third 
parameter of the comparison function, pStorage, 
must be NULL. See CM_SORTRECORD for a 
further description of the comparison function. 


CMA_PFIELDINFOLAST Pointer to the last column in the left window of 
the split details view. The default is NULL, 
causing all columns to be positioned in the left 
window. 


CMA_PFIELDINFOOBJECT © Pointer to a column that represents an object in 
the details view. This FIELDINFO structure must 
contain icons or bit maps. In-use emphasis is 
applied to this column of icons or bit maps only. 
The default is the leftmost column in the unsplit 
details view, or the leftmost column in the left 
window of the split details view. 


CMA_CNRTITLE Text for the container title. The default is NULL. 
CMA_FLWINDOWATTR Container window attributes. 
CMA_PTLORIGIN Lower-left origin of the container window in 


virtual workspace coordinates, used in the icon 
view. The default origin is (0,0). 


CMA_DELTA An application-defined threshold, or number of 
records, from either end of the list of available 
records. Used when a container needs to 
handle large amounts of data. The default is 0. 
Refer to the description of the container control 


22-72 PM Programming Reference Vol II 


CMA_SLBITMAPORICON 


CMA_SLTREEBITMAPORICON 


CMA_TREEBITMAP 
CMA_TREEICON 


CMA_LINESPACING 
CMA_CXTREEINDENT 


CMA_CXTREELINE 


CMA_XVERTSPLITBAR - 


re (BOOL) 
Success indicator. 


in the OS/2 Programming Guide for more 
information about specifying deltas. 


The size (in pels) of icons or bit maps. The 
default is the system size. 


The size (in pels) of the expanded and collapsed 
icons or bit maps in the tree icon and tree text 
views. 


Expanded and collapsed bit maps in the tree 
icon and tree text views. 


Expanded and collapsed icons in the tree icon 
and tree text views. 


The amount of vertical space (in pels) between 
the records. If this value is less than 0, a default 
value is used. 


Horizontal distance (in pels) between levels in 
the tree view. If this value is less than 0, a 
default value is used. 


Width of the lines (in pels) that show the 
relationship between items in the tree view. If 
this value is less than 0, a default value is used. 
Also, if the CA_TREELINE container attribute of 
the CNRINFO data structure’s fWindowAttr field 
is not specified, these lines are not drawn. 


The initial position of the split bar relative to the 
container, used in the details view. If this value 
is less than 0, the split bar is not used. The 
default value is negative one (-1). 


TRUE Container data was successfully set. 
FALSE Container data was not set. The WinGetLastError function may return the 


following errors: 


e¢ PMERR_INVALID_PARAMETERS 
e¢ PMERR_INSUFFICIENT_ MEMORY. 


Remarks 


The data for a container is set from the buffer addressed by the pCnrinfo parameter. The 
flags in the ulCnrinfoFl parameter show which part or parts of the pCnrinfo parameter are 
set. The flag values can be combined by using a logical OR operator (\). 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_SETRECORDEMPHASIS 


This message sets the emphasis attributes of the specified container record. 


Parameters 
param1 


pRecord (PRECORDCORE) 
Pointer to the specified container record. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of 
RECORDCORE and PMINIRECORDCORE should be used instead of 
PRECORDCORE in all applicable data structures and messages. 


param2 


usChangeEmphasis (USHORT) 
Change-emphasis-attribute flag. 


TRUE — The container record’s emphasis attribute is to be set ON if the change 
specified is not the same as the current state. 


FALSE The container record’s emphasis attribute is to be set OFF if the change 
specified is not the same as the current state. 


fEmphasisAttribute (USHORT) 
Emphasis attribute of the container record. 


The following states can be combined by using a logical OR operator (|): 
CRA_CURSORED __ Specifies that a record will be drawn with a selection cursor. 
CRA_DISABLED Specifies that a record will be drawn with unavailable-state 


emphasis. 
CRA_INUSE Specifies that a record will be drawn with in-use emphasis. 
CRA_PICKED Specifies that the container record willl be picked up as part of 


the drag set. 


CRA_SELECTED Specifies that a record will be drawn with selected-state 
emphasis. 


CRA_SOURCE Specifies that a record will be drawn with source-menu 
a1 ' emphasis. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE An error occurred. 
The WinGetLastError function may return the following errors: 


PMERR_INVALID_PARAMETERS (1208) 
PMERR_INSUFFICIENT_MEMORY (203E) 


Remarks 

For single-selection containers, the selection of the previous container record is cancelled 
before another record is selected. The selection cursor is set with the CRA_CURSORED 
attribute for single-selection containers. Only one selection cursor is allowed. 


The selection cursor must always be available to the user. Therefore, if you attempt to 
disable the selection cursor by specifying FALSE for the usChangeEmphasis parameter and 
CRA_CURSORED for the fEmphasisAttribute parameter, the 
PMERR_INVALID_ PARAMETERS error is set. In order to change the selection cursor 
attribute, TRUE should be specified for the usChangeEmphasis parameter and 
CRA_CURSORED for the fEmphasisAttribute parameter. The pRecord parameter should 
point to the record to which the selection cursor should be applied. The container control 
removes the selection cursor from the record with the cursor and applies it to the new record. 


A CN_EMPHASIS notification code is sent to the container owner if the record emphasis 
attribute is changed. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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CM_SORTRECORD 


This message sorts the container records in the container control. 


Parameters 
param1 


pfnCompare (PFN) 
Pointer to a comparison function. 


param2 | 


pStorage (PVOID) 
Application use. 


Available for application use. 


Returns 
re (BOOL) 
Success indicator. 


TRUE The records in the container were sorted. 


FALSE The records in the container were not sorted. The WinGetLastError function 
may return the following errors: 


¢ PMERR_COMPARISON_FAILED 
e PMERR_INSUFFICIENT_MEMORY. 


Remarks 
The pfnCompare parameter must be declared as: 


SHORT EXPENTRY pfnCompare(PRECORDCORE p1, PRECORDCORE p2, PVOID pStorage); 


Note: If the CCS _MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


The pfnCompare parameter points to an application-provided function that compares two 
RECORDCORE structures and returns a SHORT value that specifies their relationship. The 
pfnCompare parameter is called one or more times during the sorting process and is passed 
pointers to two RECORDCORE structures on each call. The routine must compare the 
RECORDCORE structures, and then return one of the following values: 


Value Meaning 

>0 p7 is less than p2. 

0 p71 is equal to p2. 

<0 p7 is greater than p2. 


22-76 PM Programming Reference Vol II 


The container records are sorted in increasing order, as defined by the pfnCompare 
parameter. The records can be sorted in reverse order by reversing the sense of “greater 
than” and “less than” in the pfnCompare parameter. 


If the container has only one record, the PMERR_COMPARISON FAILED error is set. 


The application must provide an NLS-enabled function for the pfnCompare parameter. The 
container control does not provide NLS enablement for sorting. 


An alternative to using the CM_SORTRECORD message is to provide an application-defined 
comparison function to sort the container records, which can be specified in the CNRINFO 
structure’s pSortRecord field. If this function is provided, the container records are sorted as 
they are inserted into the container control. If this field is NULL, the records are not sorted 
on insertion. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


CM_SETTEXTVISIBILITY 


This message sets the visibility state of text for records in the container control. 


Parameters 
param1 


bVisible (BOOL) 
Text visibility state. 


TRUE Text is visible. 
FALSE _ Text is not visible. 


param2 


Reserved (PVOID) 
Reserved value, 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE _ Text visibility state was successfully set. 
FALSE — Error occurred. 
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Remarks | | 
This message is used to set the visibility state of the text for records in the container control. 
If bVisible is TRUE, text will appear with the icons in icon view, name view, tree icon view, 
and tree name view. If bVisible is FALSE, no text appears. 


This message does not apply to any variation of text view (icon text, tree text) or details 
view. 


This message affects ALL records within the container. The visibility state of the text cannot 
be set for individual records. 


Default Processing 
The default window procedure does not expect to receive this message and, therefore, takes 
no action on it other than to return FALSE. 


WM_PICKUP 


This message adds objects to the drag set during a lazy drag operation. 


Parameters 
param1 


ptiPointerPos (POINTL) 
Pointer position in window coordinates relative to the bottom-left corner of the 
window. 


param2 


Reserved (ULONG) 
Reserved value, must be 0. 


Returns 
returns 


re (BOOL) 
Success indicator. 


‘Possible values are described in the following list: 


TRUE Message was processed. 
FALSE Message was ignored. 


Remarks 
This message will be posted to the application queue associated with the window that has 
the focus, or with the window that is to receive the pointer-button information. 
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WM_PICKUP message is sent to the window under the mouse pointer when the user 
presses the direct-manipulation button while holding down the lazy drag augmentation key, 
currently the ALT key. This message is used to inform an application that the user is 
commencing a lazy drag operation. The container control sends its owner a CN_PICKUP 
notification when it receives a message. 


Objects are added to the drag set when a WM_PICKUP message is received. The first time 
the message is received, the application initiates a lazy drag operation. Each subsequent 
WM_PICKUP message that is received during the course of the lazy drag operation indicates 
that objects are to be added to the drag set. 


Default Processing 
The default message procedure sets rc to TRUE. 


WM_PRESPARAMCHANGED (in Container Controls) 
For the cause of this message, see WM_PRESPARAMCHANGED. 


Parameters 
param1 


attrtype (ULONG) 
Presentation parameter attribute identity. 


PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX 
Sets the background color of the container window. This color is initially set 
to SYSCLR_WINDOW. 


PP_BORDERCOLOR or PP_BORDERCOLORINDEX 
Sets the color of the title separators, column separators, and split bar. This 
color is initially set to SYSCLR_WINDOWFRAME. 


PP_FONTNAMESIZE | 
Sets the font and font size of the text in the container. This font and font size 
defaults to the system font and font size. 


PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX 
Sets the color of unselected text. This color is initially set to 
SYSCLR_WINDOWTEXT. 


PP_HILITEBACKGROUNDCOLOR or PP_HILITEBACKGROUNDCOLORINDEX 
Sets the color of selection emphasis, the color of the cursor of an unselected 
item in the details view, and the color of the cursor in all other views. This 
color is initially set to SYSCLR_HILITEBACKGROUND. 


PP_HILITEFOREGROUNDCOLOR or PP_HILITEFOREGROUNDCOLORINDEX 
Sets the color of the text of a selected item in all views and the color of the 
cursor of a selected item in the details view. This color is initially set to 
SYSCLR_HILITEFOREGROUND. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns . 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The application uses the WinSetPresParam function to change presentation parameters. 

This results ina WM_PRESPARAMCHANGED (in Container Controls) message being sent 
~ to the container. 


Default Processing 
For a description of the default processing, see WM_PRESPARAMCHANGED. 
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Chapter 23. Notebook Control Window Processing 


This system-provided window procedure processes the actions on a notebook control 
(WC_NOTEBOOK). 


Purpose 


A notebook control (WC_NOTEBOOK window class) is a visual component whose specific 
purpose is to organize information on individual pages so that a user can find and display 
that information quickly and easily. It simulates a real-world notebook while improving it by 
overcoming its natural limitations. A user can select and display pages by using either a 
pointing device, such as a mouse, or the keyboard. 


The notebook is designed to be customizable to meet varying application requirements, while 
providing an easy-to-use user interface component that can be used to develop products that 
conform to the Common User Access* (CUA*) user interface guidelines. The application can 
specify different colors, sizes, and orientations for its notebooks, but the underlying function 
of the control remains the same. For a complete description of CUA notebooks, refer to the 
SAA CUA Guide to User Interface Design and the SAA CUA Advanced Interface Design 
Reference. 


Notebook Control Styles 


Notebook control window styles can be set with a notebook is created. The following styles 
can be set when creating a notebook control window. If no styles are specified, defaults, 
which are identified in the following descriptions, are used. 


e Specify one of the following to determine whether the control is a a solid bound or spiral 
bound notebook, or a catalog: 


BKS_SOLIDBIND Paints a solid binding on the notebook. This is the 
default. 

BKS_SPIRALBIND Paints a spiral binding on the notebook. 

¢ Specify one of the following to determine where the back pages are positioned: 

BKS_BACKPAGESBR Paints back pages on the notebook’s bottom and right 
sides. This is the default. 

BKS_BACKPAGESBL Paints back pages on the notebook’s bottom and left 
sides. 

BKS_BACKPAGESTR Paints back pages on the notebook’s top and right sides. 

BKS_BACKPAGESTL Paints back pages on the notebook’s top and left sides. 
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¢ Specify one of the following to determine the side of the notebook on which the major 
tabs are positioned. Valid combinations with back pages styles are noted in each 
definition. 


BKS_MAJORTABRIGHT Places major tabs on the notebook’s right edge. Only 
valid in combination with BKS_BACKPAGESBR or 
BKS_BACKPAGESTR. This is the default when either of 
these back pages styles is used. 


BKS_MAJORTABLEFT Places major tabs on the notebook’s left edge. Only valid 
in combination with BKS_BACKPAGESBL or 
BKS_BACKPAGESTL. This is the default when 
BKS_BACKPAGESTL is used. 


BKS MAJORTABTOP Places major tabs on the notebook’s top edge. Only valid 
| in combination with BKS_BACKPAGESTR or 
BKS_BACKPAGESTL. 


BKS_MAJORTABBOTTOM Places major tabs on the notebook’s bottom edge. Only 
valid in combination with BKS_BACKPAGESBR or 
BKS_BACKPAGESBL. This is the default when 
BKS_BACKPAGESBL is used. 


e Specify one of the following to set the shape of the notebook tabs: 


BKS_SQUARETABS Draws tabs with square edges. This is the default. 
BKS_ROUNDEDTABS Draws tabs with rounded edges. 
BKS_POLYGONTABS Draws tabs with polygon edges. 


e Specify one of the following to position the status line text: 


BKS_STATUSTEXTLEFT Left-justifies status line text. This is the default. 
BKS_STATUSTEXTRIGHT _ Right-justifies status line text. 
BKS_STATUSTEXTCENTER Centers status line text. © 


¢ Specify one of the following to position the tab text: 


BKS_TABTEXTCENTER Centers tab text. This is the default. 
BKS_TABTEXTLEFT Left-justifies tab text. 
BKS_TABTEXTRIGHT Right-justifies tab text. 


Notebook Control Data 
See the following for descriptions of the notebook control data structures: 


e “BOOKTEXT”’ on page A-23 
“DELETENOTIFY” on page A-46 
e “PAGESELECTNOTIFY” on page A-140. 
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Notebook Control Notification Messages 


These messages are initiated by the notebook control window to notify its owner of 
significant events. 


WM_CONTROL (in Notebook Controls) 
For the cause of this message, see WM_CONTROL. 


Parameters 


param1 


id (USHORT) 


Control-window identity. 


notifycode (USHORT) 


param2 


Notify code. 


The notebook control uses these notification codes: 


BKN_HELP 


BKN_NEWPAGESIZE 


BKN_PAGEDELETED 


BKN_PAGESELECTED 


BKN_PAGESELECTEDPENDING 


notifyinfo (ULONG) 


Notify code information. 


Indicates the notebook control has received a 
WM_HELP message. 


Indicates the dimensions of the application 
page window have changed. 


Indicates a page has been deleted from the 
notebook. 


Indicates a new page has been brought to the 
top of the notebook. This notification is sent 
after the page is turned. 


Indicates a new page is about to be brought to 
the top of the notebook. This notification is 
sent before the page is actually turned. 


If the application does not want the page to be 
turned, it sets the u/PageldNew field of the 
PAGESELECTNOTIFY structure to NULL 
before returning. 


The value of this parameter depends on the value of the notifycode parameter. 
When the value of the notifycode parameter is BKN_HELP, this parameter is the ID 
of the notebook page (u/Pageld) whose tab contains the selection cursor. 
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When the value of the notifycode parameter is BKN_PAGESELECTED or 
BKN_PAGESELECTEDPENDING, this parameter is a pointer to the 
PAGESELECTNOTIFY structure. 


When the value of the notifycode parameter is BKN_PAGEDELETED, this 
parameter is a pointer to the DELETENOTIFY structure. 


Otherwise, this parameter is the notebook control window handle. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 


The notebook control window procedure generates this message and sends it to its owner, 
informing the owner of this event. 


Default Processing 
For a description of the default processing, see WM_CONTROL. 


WM_CONTROLPOINTER (in Notebook Controls) 
For the cause of this message, see WM_CONTROLPOINTER. 


For a description of the parameters, see WM_CONTROLPOINTER. 


Remarks 
For the appropriate remarks, see WM_CONTROLPOINTER. 


Default Processing 
For the default processing, see WM_CONTROLPOINTER. 


WM_DRAWITEM (in Notebook Controls) 
This notification message is sent to the owner of a notebook control each time a tab’s 
content is to be drawn by the owner of the notebook. The tab’s content is drawn by the 
owner unless the owner sets the tab text or bit map by sending a BKM_SETTABTEXT or 
BKM_SETTABBITMAP message, respectively, to the notebook control. 


Parameters 
param1 


id (USHORT) 
Window identifier. 


The window identifier of the notebook control sending this notification message. 
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param2 


powneritem (POWNERITEM) 
Pointer to an OWNERITEM data structure. 


The following list defines the OWNERITEM data structure fields that apply to the 
notebook control. See “OWNERITEM” on page A-136 for the default field values. 


hwnd (HWND) 
Notebook window handle. 


hps (HPS) 
Presentation-space handle. 


fsState (ULONG) 
Notebook window style flags. See “Notebook Control Styles” on page 23-1 for 
descriptions of these style flags. 


fsAttribute (ULONG) 
Page attribute flags for the tab page. See BKM_INSERTPAGE for descriptions 
of these attribute flags. 


fsStateOld (ULONG) 
Reserved. 


fsAttributeOld (ULONG) 
Reserved. 


rciltem (RECTL) 
Tab rectangle to be drawn in window coordinates. 


iditem (LONG) 
Reserved. 


hitem (ULONG) 
Current page ID (u/Pagel/d) for which the content of a tab is to be drawn. 


Returns 
rc (BOOL) 
Content-drawn indicator. 


TRUE The owner draws the tab’s content. 
FALSE _ If the owner does not draw the tab’s content, the owner returns this value and 
the notebook control draws the tab’s content. 


Remarks 

If an application uses notebook controls that contain tab pages, the default condition is for 
the application to draw the contents of the tab each time a tab page is displayed. This 
situation applies particularly if the content of the tab is not one of the supported formats. 


The notebook control window procedure generates this message and sends it to its owner, 


informing the owner that the content of a tab is to be drawn. The owner is given the 
opportunity to draw the content of the tab and to indicate that the content of the tab has been 
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drawn or that the notebook control is to draw it. To indicate that the notebook control is to 
draw the content of the tab, the owner sends either a BKM_SETTABTEXT or a 
BKM_SETTABBITMAP message to the notebook control. 


Default Processing 
For a description of the default processing, see WM_DRAWITEM. 
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Notebook Control Window Messages 


This section describes the notebook control window procedure actions on receiving the 
following messages. 


BKM_CALCPAGERECT 


This message calculates an application page rectangle from a notebook rectangle or 
calculates a notebook rectangle from an application page rectangle, depending on the setting 
of the bPage parameter. 


Parameters 
param1 


pRectl (PRECTL) 
Pointer to the RECTL structure that contains the coordinates of the rectangle. 


If the bPage parameter is TRUE, this structure contains the coordinates of a 
notebook window on input, and on return it contains the coordinates of an 
application page window. 


If the bPage parameter is FALSE, this structure contains the coordinates of an 


application page window on input, and on return it contains the coordinates of a 
notebook window. 


param2 


bPage (BOOL) 
Window specifier. 


Specifies whether the window coordinates to calculate are for a notebook window or 
an application page window. 


TRUE An application page window is calculated. 
FALSE A notebook window is calculated. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Coordinates were successfully calculated. 
FALSE Unable to calculate coordinates. This is returned if an invalid RECTL structure 
is specified in the pRect/ parameter. 


Remarks 

The application can use this message to determine the size of either the notebook window or 
the application page window. It can also be used when the application handles the position 
and size of the application page window. 
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To calculate the application page rectangle, specify the coordinates of the notebook window 
in the pRectl parameter and TRUE in the bPage parameter. The notebook control then uses 
the coordinates specified in the pRect! parameter to calculate and return the coordinates of 
the application page window. 


_To calculate the notebook rectangle, specify the coordinates of the application page window 
in the pRect/ parameter and FALSE in the bPage parameter. The notebook control then 
uses the coordinates specified in the pRect! parameter to calculate and return the 
coordinates of the notebook window. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


BKM_DELETEPAGE 


This message deletes the specified page or pages from. the notebook data list. 


Parameters 
param1 


ulPageld (ULONG) 
Page identifier. 


Page identifier for deletion. This is ignored if the BKA_ALL attribute of the 
usDeleteFlag parameter is specified. 


param2 


usDeleteFlag (USHORT) 
Page range attribute. 


Attribute that specifies the range of pages to be deleted. 
BKA_SINGLE Delete a single page. 


BKA_TAB If the page ID specified is that of a page with a major tab attribute, 
delete that page and all as pages up to the next page that 
has a major tab attribute. 


If the page ID specified is that of a page with a minor tab attribute, 
delete that page and ail subsequent pages up to the next page that 
has either a major or minor tab attribute. 


This attribute should only be specified for pages that have major or 
minor tab attributes. If a page with neither of these attributes is 
specified, FALSE is returned and no pages are deleted. 


BKA_ALL Delete all pages in the notebook. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Pages were successfully deleted. 

FALSE Unable to delete the page or pages. This is returned if an invalid page ID is 
specified for the u/Page/d parameter or if the BKA_TAB attribute is specified 
for a page that has neither a major nor a minor tab attribute. 


Remarks 
The notebook frees all storage that it has allocated for the deleted page or pages. The 
application is responsible for deleting the application page window and bit map, if created. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


BKM_INSERTPAGE 


This message inserts the specified page into the notebook data list. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID for placement. 


Page identifier used for the placement of the inserted page. This identifier is 
ignored if the BKA_FIRST or BKA_LAST attribute of the usPageOrder parameter is 
specified. 


param2 


usPageStyle (USHORT) 
Style attributes. 


Attributes that specify the style to be used for an inserted page. You can specify 
one attribute from each of the following groups by using logical OR operators (|) to 
combine attributes. 


¢ Specify the following for automatic page position and size: 


BKA_AUTOPAGESIZE Notebook handles the positioning and sizing of the 
application page window specified in the 
BKM_SETPAGEWINDOWHWND message. 
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' @ Specify the following to display status area text: 


BKA_STATUSTEXTON 
Page is to be displayed with status area text. If this attribute is not 
specified, the application cannot associate a text string with the status area 
of the page being inserted. 


¢ Specify one of the following if the page is to have a major or minor tab attribute: 


BKA_MAJOR Inserted page will have a major tab attribute. 
BKA_MINOR Inserted page will have a minor tab attribute. 


usPageOrder (USHORT) 
Order attributes. 


Placement of page relative to the previously inserted pages. You can specify one of 
the following attributes: 


BKA_FIRST Insert page at the front of the notebook. The page ID specified in 
the ul/Pageld parameter for param? is ignored if this is specified. 


BKA_LAST Insert page at the end of the notebook. The page ID specified in the 
ulPageld parameter for param is ignored if this is specified. 


BKA_NEXT _ Insert page after the page whose ID is specified in the u/Pageld . 
parameter for param1. lf the page ID specified in the ulPageld 
parameter is invalid, NULL is returned and no page is inserted. 


BKA_PREV __ Insert page before the page whose ID is specified in the ul/Pageld 
parameter for param7. lf the page ID specified in the ulPageld 
parameter is invalid, NULL is returned and no page is inserted. 


Returns 
ulPageld (ULONG) 
Page ID for insertion. 


Identifier for the inserted page. 


NULL The page was not inserted into the notebook. An invalid page ID was specified 
for the ulPageld parameter for param? or not enough space was available to 
allocate the page data. 


Other Identifier for the inserted page. 


Remarks 

The notebook control allocates and manages the storage needed for the new page. If 
neither the BKA_MAJOR or BKA_MINOR attribute is specified, the page is inserted with no 
tab attributes. 


If the application does not specify the BKA_AUTOPAGESIZE attribute, it must handle the 


positioning and sizing of the application page window when it receives the 
BKN_NEWPAGESIZE notification code. | 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


BKM_INVALIDATETABS 


This message repaints all of the tabs in the notebook. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE _ Tabs painted successfully. 
FALSE Tabs were not painted. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


BKM_QUERYPAGECOUNT 


This message queries the number of pages. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID or 0. 


Page identifier from which to start the query, or 0. If this parameter is set to 0, the 
query begins with the first page. 
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param2 


usQueryEnd (USHORT) 
Query end attribute. 


Attribute that ends the page count query. 


BKA_MAJOR Query the number of pages between the page ID specified in the 
ulPageld parameter and the next page that has the BKA_MAJOR_ 
attribute. The page that has the BKA_MAJOR attribute is not 
included in the page count. 


BKA_MINOR Query the number of pages between the page ID specified in the 
| ulPageld parameter and the next page that has the BKA_MINOR 
attribute. The page that has the BKA_MINOR attribute is not 
included in the page count. 


BKA_END Query the number of pages between the page ID specified in the 
ulPageld parameter and the last page. When this attribute is 
specified, the page count includes the last page plus the 
notebook’s back cover. 


Returns 
pageCount (SHORT) 
Number of pages. 


Number of pages in the notebook. 


BOOKERR_INVALID_PARAMETERS . An invalid page ID was specified for the 
. ulPageld parameter. 


Other Number of pages for the specified range. If the 
notebook is empty or no pages are found in the 
range, this value is 0. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 
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BKM_QUERYPAGEDATA 


This message queries the 4 bytes of application reserved storage associated with the 
specified page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


The page identifier of the page from which to retrieve the 4 bytes of data. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulPageData (ULONG) 
Page data. 


Application-defined page data. 


BOOKERR_INVALID_PARAMETERS _ Ahn invalid page ID was specified for the 
ulPageld parameter. 


0 No page data was set for the page specified in 
the ulPageld parameter. 
Other Application-defined page data. 
Remarks 


This data is set by using the BKM_SETPAGEDATA message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


BKM_QUERYPAGEID 


This message queries the page identifier for the specified page. 
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Parameters 
param1 


ulPageld (ULONG) 
Location page !D. 


Page identifier used for locating the requested page. This identifier is ignored if the 
BKA_FIRST, BKA_LAST, or BKA_TOP attribute is specified. 


param2 


usQueryOrder (USHORT) 
Page ID query order. 


Order in which to query the page identifier. 


BKA_FIRST Get the page identifier for the first page. The page ID specified in 
the ul/Pageld parameter for param1 is ignored if this is specified. 


BKA_LAST _ Get the page identifier for the last page. The page ID specified in 
the u/Pageld parameter for param is ignored if this is specified. 


BKA_NEXT Get the page identifier for the page after the page whose ID is 
specified in the ulPageld parameter for param?. If the page ID 
specified in the u/Pageld parameter is invalid, 
BOOKERR_INVALID_ PARAMETERS is returned. 


BKA_PREV _ Get the page identifier for the page before the page whose ID is 
specified in the u/Pageld parameter for param1. lf the page ID 
specified in the u/Pageld parameter is invalid, 
BOOKERR_INVALID_PARAMETERS is returned. 


BKA_TOP Get the page identifier for the page currently visible in the notebook. 
The page ID specified in the ul/Pageld parameter for param? is 
ignored if this is specified. 


usPageStyle (USHORT) 
Page style. 


Page style for which to query the page identifier. !f neither of these attributes is 
specified, the usPageStyle parameter is ignored. 


BKA_ MAJOR Query page with major tab attribute. 


BKA_MINOR Query page with minor tab attribute: If a major tab page is found 
before the minor tab page, the search is ended and 0 is returned. 


Returns 
ulPageld (ULONG) 
Retrieved page ID. 
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BOOKERR_INVALID_PARAMETERS _ Returned if the page ID specified for the 
ulPageld parameter for param? is invalid when 
specifying either the BKA_PREV or BKA_NEXT 
attribute in the usQueryOrder parameter. 


0 Requested page not found. This could be an 
indication that the end or front of the list has 
been reached, or that the notebook is empty. 


Other Retrieved page identifier. 
Remarks 


If the BKA_FIRST, BKA_LAST, or BKA_TOP attribute is specified, the page ID in the 
ulPageld parameter is ignored. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


BKM_QUERYPAGEINFO 


This message queries the page information associated with a notebook page. 


Parameters 
param1 


ulPageld (ULONG) 


Id of the notebook page whose information is to be queried. 


param2 


pPagelnfo (PPAGEINFO) 
Pointer to a notebook page information structure. 
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Returns 
returns 


re (BOOL) 
Success indicator. 


Possible values are described in the following list: 


TRUE Message was processed. 
FALSE Message was ignored. 


Remarks 
This message handles the following notebook messages: 


BKM_QUERYPAGEDATA 
BKM_QUERYPAGEWINDOWHWND 
BKM_QUERYSTATUSLINETEXT 
BKM_QUERYTABBITMAP 
BKM_QUERYTABTEXT 


Default Processing 
The default message procedure sets rc to TRUE. 


BKM_QUERYPAGESTYLE 


This message queries the style that was set when the specified page was inserted. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


Page identifier of the page from which to query the style setting. 


param2_ 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
usPageStyle (USHORT) 
Page style data. 


BOOKERR_INVALID_PARAMETERS _ Ahn invalid page ID was specified for the 
ulPageld parameter. 
Other Page style data. 


Remarks 
This style data is set when the page is inserted, which is done by using the 
BKM_INSERTPAGE message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


BKM_QUERYPAGEWINDOWHWND 
This message queries the application page window handle associated with the specified 
page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


Page identifier of the page whose window handle is requested. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
hwndPage (HWND) 
Window handle. 


Handle of the application page window associated with the specified page identifier. 


BOOKERR_INVALID_PARAMETERS _ An invalid page ID was specified for the 
ulPageld parameter. 


NULLHANDLE No application page window handle is 
associated for the page specified in the 
ulPageld parameter. 


- Other Handle of the application page window 
associated with the specified page identifier. 
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Remarks 
The application page window handle is set by using the BKM_SETPAGEWINDOWHWND 
message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULLHANDLE. 


BKM_QUERYSTATUSLINETEXT 


This message queries the status line text, text size, or both for the specified page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


Page identifier of the page whose status line text is requested. 


param2 


pBookText (PBOOKTEXT) 
Pointer to a BOOKTEXT data structure. See “BOOKTEXT” on page A-23 for 
definitions of this structure’s fields as they apply to the 
BKM_QUERYSTATUSLINETEXT message. 


Returns 
statusTextLen (USHORT) . 
String length. 


Length of the status line text string. 


BOOKERR_INVALID_PARAMETERS _ An invalid page ID was specified for the 
ulPageld parameter or the structure specified 
for the pBookText parameter is invalid. 


0 . No text data has been set 
(BKM_SETSTATUSLINETEXT) for the page 
specified in the u/Pageld parameter. 


Other Length of the returned status line text string. 


Remarks 

The size of the status line text string can be queried by specifying 0 for the textLen field of 
the BOOKTEXT data structure. In this way, the application can determine the size of the 
buffer needed to store the status line text string. The null character at the end of the text 
string is not included in the returned length. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action other than to return 0. 


BKM_QUERYTABBITMAP 


This message queries the bit-map handle associated with the specified page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


Page identifier of the page whose bit-map handle is requested. This should be a 
page for which a BKA_MAJOR or BKA_MINOR attribute has been specified. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
hbm (HBITMAP) 
Bit-map handle. 


Handle of the bit map associated with the specified page identifier. 


BOOKERR_INVALID_PARAMETERS _ An invalid page ID was specified for the 
ulPageld parameter. 


NULLHANDLE No bit-map handle is associated with the page 
specified in the u/Page/ld parameter. 


Other Handle of the bit map associated with the 
Specified page identifier. 


Remarks 
The tab bit-map handle is set by using the BKM_SETTABBITMAP message. 


If this message is sent for a page having both major and minor tab attributes, the notebook 
returns the bit map associated with the major tab. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return NULLHANDLE. 
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BKM_QUERYTABTEXT 


This message queries the text, text size, or both for the specified page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


Page identifier of the page whose tab text is requested. This should be a page for 
which a BKA_MAJOR or BKA_MINOR attribute has been specified. 


param2 


pBookText (PBOOKTEXT) 
Pointer to a BOOKTEXT data structure. 


See “BOOKTEXT” on page A-23 for definitions of this structure’s fields as they 
apply to the BKM_QUERYTABTEXT message. 


Returns 
tabTextLen (USHORT) 
Length of the tab text string. 


BOOKERR_INVALID_PARAMETERS _ An invalid page ID was specified for the 
ulPageld parameter or the structure specified 
for the pBookText parameter is invalid. 


0 No text data has been set 
(BKM_SETTABTEXT) for the page specified in 
the ul/Pageld parameter. 


Other | Length of the returned tab text string. 


Remarks 

The size of the tab text string can be queried by specifying 0 for the tabTextLen field in the 
BOOKTEXT data structure. In this way, the application can determine the size of the buffer 
needed to store the tab text string. The null character at the end of the text string is not 
included in the returned length. 


If this message is sent for a page having both major and minor tab attributes, the notebook 
returns the text which is associated with the major tab. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 
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BKM_SETDIMENSIONS 


This message sets the height and width for the major tabs, minor tabs, or page buttons. 


Parameters 
param1 


usWidth (USHORT) 
Width value to set. 


usHeight (USHORT) 
Height value to set. 


param2 


usType (USHORT) 
Notebook region. 


Notebook region for which the dimensions are to be set. Valid values are: 


¢ BKA_MAJORTAB 
¢ BKA_MINORTAB 
¢ BKA_PAGEBUTTON. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Dimensions were successfully set. 
FALSE Unable to set dimensions. Returned if an invalid value is specified for the 
usType parameter or if the dimensions are invalid. — 


Remarks 

If either the BKA_MAJORTAB or BKA_MINORTAB attribute is specified for the usType 
parameter, the minimum width and height for display is 7 pels to allow space for the tab 
border and the selection cursor. If the tabs or page buttons are not to be displayed, the 
height and width can be set to 0. 


If the new dimensions cause the notebook size to change, the notebook sends a 
BKN_NEWPAGESIZE notification code to the application. 


Default Processing | 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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BKM_SETNOTEBOOKCOLORS 


This message sets the colors for the major tab text and background, the minor tab text and 
background, and the notebook page background. 


Parameters 
param1 


ulColor (ULONG) 
Color value to set. 


param2 


usBookAttr (USHORT) 
Notebook region. 


Notebook region whose color is to be set. Valid values are: 


BKA_BACKGROUNDPAGECOLOR or BKA_BACKGROUNDPAGECOLORINDEX 
Page background. This color is initially set to 
SYSCLR_PAGEBACKGROUND. 


BKA_BACKGROUNDMAJORCOLOR or 
BKA_BACKGROUNDMAJORCOLORINDEX 
Major tab background. This color is initially set to 
SYSCLR_PAGEBACKGROUND. 


BKA_BACKGROUNDMINORCOLOR or BKA_BACKGROUNDMINORCOLORINDEX 
Minor tab background. This color is initially set to 
SYSCLR_PAGEBACKGROUND. 


BKA_FOREGROUNDMAJORCOLOR or 
BKA_FOREGROUNDMAJORCOLORINDEX 
Major tab text. This color is initially set to SYSCLR_WINDOWTEXT. 


BKA_FOREGROUNDMINORCOLOR or BKA_FOREGROUNDMINORCOLORINDEX 
Minor tab text. This color is initially set to SYSCLR_WINDOWTEXT. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Colors were successfully set. 
FALSE Unable to set colors. Returned if an invalid notebook attribute is specified for 
the usBookAttr parameter. 
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Remarks 

The notebook background, border, selection cursor, and status line text colors are mapped to 
system presentation attributes. See WM_PRESPARAMCHANGED (in Notebook Controls) 
for information about setting the color of these regions. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


BKM_SETPAGEDATA 


This message sets the 4 bytes of application reserved storage associated with the specified 
page. 


Parameters 
param1 


ulPageld (ULONG) 
Page !D. 


The page identifier of the page from which to set the 4 bytes of data. 


param2 


ulPageData (ULONG) 
Page data. 


Application-defined page data. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Page data was successfully set. 
FALSE Unable to set page data. This value is returned if the page ID specified in the 
ulPageld parameter is invalid. 


Remarks 
This data can be queried by using the BKM_QUERYPAGEDATA message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore faxes 
no action on it other than to return FALSE. 
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BKM_SETPAGEINFO 
This message sets the page information associated with notebook page which contains a 
single message. 


Parameters 
param1 


ulPageld (ULONG) 
Id of the notebook page whose information is to be set. 


param2 


pPagelnfo (PPAGEINFO) 
Pointer to a notebook page information structure. 


Returns 
returns 


re (BOOL) 
Success indicator. 


Possible values are described in the following list: 


TRUE Message was processed. 
FALSE Message was ignored. - 


Remarks | 
This message provides an application with the ability to associate a window handle, a static 
dialog resource or a dynamic dialog resource with a notebook page. The notebook can 
automatically load the dialog resource when the resource is associated with the page or 
when the page is turned. 


This message performs the tasks of the following notebook messages: 


e BKM_SETPAGEDATA 

¢ BKM_SETPAGEWINDOWHWND 
e BKM _SETSTATUSLINETEXT 

e BKM_SETTABBITMAP 

¢ BKM_SETTABTEXT 


Default Processing 
The default message procedure sets rc to TRUE. 
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BKM_SETPAGEWINDOWHWND 


This message associates an application page window handle with the specified notebook 
page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


The page ID of the notebook page with which the application page window is to be 
associated. 


param2 


hwndPage (HWND) 
Window handle. 


The handle of the application page window that is to be associated with the 
notebook page identified in the u/Pageld parameter. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE = Application page window handle was successfully set. 
FALSE Unable to set application page window handle. This value is returned if the 
page ID specified for the u/Pageld parameter is invalid. 


Remarks 

The notebook shows the application page window specified in the hwndPage parameter 
whenever the notebook page specified in the ul/Pageld parameter is brought to the top of the 
notebook. If the BKA_AUTOPAGESIZE attribute is specified when that page is inserted into 
the notebook, the notebook aiso handles the sizing and positioning of the application page 
window. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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BKM_SETSTATUSLINETEXT 


This message associates a text string with the specified page’s status line. 


Parameters 
param1 


ulPageld (ULONG) 
Page !D. 


The page identifier with which to associate the text string. 


param2 


pString (PSZ) 
Pointer to a text string that ends in a null character. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Status line text was successfully set. 

FALSE Unable to set status line text. This value is returned if the page ID specified in 
the u/Pageld parameter is invalid or if the page was inserted without 
specifying the BKA_STATUSTEXTON attribute. 


Remarks 
If the text is longer that the status area length, only the text that fits in the status area is 
displayed. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


BKM_SETTABBITMAP 


This message associates a bit-map handle with the specified page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


The page identifier with which to associate the bit-map handle. This should be a 
page for which a BKA_MAJOR or BKA_MINOR attribute has been specified. 
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param2 


hbm (HBITMAP) 
Bit-map handle. 


Returns 
re (BOOL) 
Success indicator. 


TRUE ~ Tab bit map was successfully set. 


FALSE Unable to set tab bit map. If the page ID specified in the ul/Pageld parameter 
is invalid or if it identifies a page that does not have a BKA_MAJOR or 
BKA_MINOR attribute, FALSE is returned and no bit map is associated with 
the page. 


Remarks 
If this message is sent for a page having both major and minor tab attributes, the notebook 
sets both the major and minor tab bit maps. 


When displayed, the bit map is stretched to fit the size of the tab. If a tab has rounded or 
polygonal edges, the bit map is sized to fit the rectangular area of the tab, as shown in 
Figure 23-1. 


Bitmap Stretched to Fit 
Rectangular Area 


Square Polygonal 
Tab Tab 


Figure 23-1. Tabs Showing Rectangular Area Used to Size a Bit Map 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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BKM_SETTABTEXT 


This message associates a text string with the specified page. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


The page identifier with which to associate the text string. This should be a page 
for which a BKA_MAJOR or BKA_MINOR attribute has been specified. 


param2 


pString (PSZ) 
Pointer to a text string that ends with a null character. 


Returns | 
re (BOOL) 
Success indicator. 


TRUE _ Tab text was successfully set. 

FALSE Unable to set tab text. If the page ID specified in the ul/Pageld parameter is 
invalid or if it identifies a page that does not have a BKA_MAJOR or 
BKA_MINOR attribute, FALSE is returned and no text string is associated with 
the page. 


Remarks 
The text is centered from the tab edges. 


The application can define a mnemonic key when sending this message by placing a tilde (-) 
character before the character that is to be the mnemonic key. The notebook brings this 
page to the top whenever the user presses the mnemonic key. 


The mnemonic key processing is not case-sensitive, so the user can type the mnemonic 
character in either upper or lower case. 


The application can remove or change the mnemonic key by sending additional 
BKM_SETTABTEXT messages for the specified page. 


If this message is sent for a page having both major and minor tab attributes, the notebook 
sets both the major and minor tab text. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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BKM_TURNTOPAGE 


This message brings the specified page to the top of the notebook. 


Parameters 
param1 


ulPageld (ULONG) 
Page ID. 


The page identifier that is to become the top page. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
fSuccess (BOOL) 
Success indicator. 


TRUE — The page was successfully moved to the top of the notebook. 
FALSE Unable to move the page to the top of the notebook. This value is returned if 
the page ID specified in the u/Pageld parameter is invalid. 


Remarks 
The application receives a BKN_PAGESELECTED notification code when the new page is 
brought to the top of the notebook. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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WM_CHAR (in Notebook Controls) 


For the cause of this message, see WM_CHAR. 


For a description of the parameters, see WM_CHAR. 


Remarks 
If the application page window has the focus (for example, the cursor is on a control within 
the top page dialog), the notebook handles the following keyboard interaction: 


Alt+Up Arrow Sets the focus to the notebook window. 


lf the notebook control has the focus (for example, the cursor is on the major tab, minor tab 
or page turning button), the notebook handles the following keyboard interactions: 


Alt+Down Arrow Sets the focus to the application page window. 
Tab Moves the selection cursor to the next position or control. 
Shift+Tab Moves the selection cursor to the previous position or control. 


Down Arrow or Right Arrow 
Moves the selection cursor to the next major or minor tab. If 
either of these keys is pressed while the selection cursor is on 
a major tab, the cursor moves to the next major tab. If either 
of these keys is pressed while the selection cursor is on a 
minor tab, the cursor moves to the next minor tab. If the next 
tab is not visible, the tabs are scrolled to bring the next tab into 
view. If the end of the tabs is reached, scrolling ends. 


Up Arrow or Left Arrow Moves the selection cursor to the previous major or minor tab. 
If either of these keys is pressed while the selection cursor is 
on a major tab, the cursor moves to the previous major tab. If 
either of these keys is pressed while the selection cursor is on 
a minor tab, the cursor moves to the previous minor tab. If the 
previous tab is not visible, the tabs are scrolled to bring the 
previous tab into view. If the beginning of the tabs is reached, 
scrolling ends. 


Enter or Spacebar The cursored tab page becomes the top page of the notebook. © 


Mnemonics Brings the page whose tab contains the mnemonic character to 
the top of the notebook whenever the user presses the 
mnemonic key. Mnemonic key definition is provided by using 
the BKM_SETTABTEXT message. Coding a mnemonic 
character () before a text character in the BKM_SETTABTEXT 
message causes that character to be underlined in the tab’s 
text string and activates it as a mnemonic selection character. 
The mnemonic key pressing is not case-sensitive, so the user 
can type the mnemonic character in either upper or lower case. 


PgDn or Alt+PgDn Brings the next page to the top of the notebook and sets the 
selection cursor on the associated tab, if there is one. 
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PgUp or Alt+PgUp Brings the previous page to the top of the notebook and sets 
the selection cursor on the associated tab, if there is one. 


Home Brings the first page of the notebook to the top and sets the 
selection cursor on the associated tab, if there is one. 


End Brings the last page of the notebook to the top and sets the 
selection cursor on the associated tab, if there is one. 


Default Processing 
For a description of the default processing, see WM_CHAR. 


WM_PRESPARAMCHANGED (in Notebook Controls) 
For the cause of this message, see WM_PRESPARAMCHANGED. 


Parameters 
param1 


attrtype (ULONG) 
Attribute type. 


Presentation parameter attribute identity. 


PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX 
Sets the background color of the notebook window. This color is initially set 
to SYSCLR_FIELDBACKGROUND. 


PP_BORDERCOLOR or PP_BORDERCOLORINDEX 
Sets the color of the notebook outline. This color is nel set to 
SYSCLR_WINDOWFRAME. 


PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX 
Sets the color of text on the status line. This color is initially set to 
SYSCLR_WINDOWTEXT. 


PP_HILITEBACKGROUNDCOLOR or PP_HILITEBACKGROUNDCOLORINDEX 
Sets the color of the selection cursor. This color is initially set to 
SYSCLR_HILITEBACKGROUND. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks | 
- The application uses this message to notify the notebook that a given inherited presentation 
parameter has changed. 


Default Processing 
For a description of the default processing, see WM_PRESPARAMCHANGED. 


WN_SIZE (in Notebook Controls) 


For the cause of this message, see WM_SIZE. 


For a description of the parameters, see WM_SIZE. 


Remarks 

When the size of the notebook window changes, all of the regions are recalculated. The 
notebook sends a BKN_NEWPAGESIZE notification code to the application. The notebook 
sets the position and size of application page windows that are associated with pages for 
whom the BKA_AUTOPAGESIZE attribute is set. 


Default Processing 
For a description of the default processing, see WM_SIZE. 
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Chapter 24. Slider Control Window Processing 


This system-provided window procedure processes the actions on a slider control 
(WC_SLIDER). 


Purpose 


A slider control (WC_SLIDER window class) is a visual component whose specific purpose is 
to allow a user to set, display, or modify a value by moving a slider arm along a slider shaft. 
Sliders are typically used to allow a user to easily set values that have familiar increments, 
such as feet, inches, degrees, decibels, and so forth. 


However, they can also be used for other purposes when immediate feedback is necessary, 
such as to blend colors or to show the percentage of a task that has completed. For 
example, an application might allow a user to mix and match color shades by moving a slider 
arm, or a read-only slider could be provided that shows how much of a task has completed 
by filling in the slider shaft as the task progresses. These are just a few examples to show 
you the many ways in which sliders can be used. 


The appearance of and user interaction for a slider is similar to the appearance of and user 
interaction for a scroll bar. However, these two controls are not interchangeable because 
each has a distinct purpose. The scroll bar is used to scroll into view information that is 
outside a window’s client area, while the slider is used to set, display, or modify that 
information, whether it is in the client area or not in the client area. 


The slider is designed to be customizable to meet varying application requirements, while 
providing an easy-to-use user interface component that can be used to develop products that 
conform to the Common User Access (CUA) user interface guidelines. The application can 
specify different scales, sizes, and orientations for its sliders, but the underlying function of 
the control remains the same. For a complete description of CUA sliders, refer to the SAA 
CUA Guide to User Interface Design and the SAA CUA Advanced Interface Design 
Reference. 


Slider Control Styles 


Slider control window styles are set when a slider window is created. The following styles 
can be set when creating a slider control window. If no styles are specified, defaults, which 
are identified in the following descriptions, are used. 


e Specify either of the following to determine the slider’s orientation: 


SLS_ HORIZONTAL 
The slider is positioned horizontally. The slider arm can move left and right on the 
slider shaft. A scale can be placed on top of the slider shaft, below the slider 
shaft, or in both places. This is the default orientation of the slider. 
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SLS_VERTICAL 
The slider is positioned vertically. The slider arm can move up and down the 
Slider shaft. A scale can be placed on the left side of the slider shaft, on the right 
side of the slider shaft, or in both places. 
* Specify one of the following to position the slider within the slider window: 
SLS_CENTER 


The slider is centered in the slider window. This is the default positioning of the 
slider. 


SLS_BOTTOM 


The slider is positioned at the bottom of the slider window. This is valid for 
horizontal sliders only. 


SLS TOP 


The slider is positioned at the top of the slider window. This is valid for horizontal 
sliders only. 


SLS_LEFT 


The slider is positioned at the left edge of the slider window. This is valid for 
vertical sliders only. . 


SLS_RIGHT 
The slider is positioned at the right edge of the slider window. This is valid for 
vertical sliders only. 
e Specify one of the following to determine the location of the scale on the slider shaft: 
SLS_PRIMARYSCALE1 
The slider uses the increment and spacing specified for scale 1 as the 
incremental value for positioning the slider arm. Scale 1 is displayed above the 


slider shaft of a horizontal slider and to the right of the slider shaft of a vertical 
slider. This is the default for a slider. 


SLS_PRIMARYSCALE2 


The slider uses the increment and spacing specified for scale 2 as the 
incremental value for positioning the slider arm. Scale 2 is displayed below the — 
slider shaft of a horizontal slider and to the left of the slider shaft of a vertical 


slider. 
e Specify one of the following to determine the slider arm’s home position: 
SLS HOMELEFT 


The slider uses the left edge of the slider as the base value for incrementing. This 
is the default for horizontal sliders and is valid for horizontal sliders only. 


SLS_HOMERIGHT 


The slider uses the right edge of the slider as the base value for incrementing. 
This is valid for horizontal sliders only. 


24-2 PM Programming Reference Vol II 


SLS_HOMEBOTTOM 
The slider uses the bottom of the slider as the base value for incrementing. This 
is the default for vertical sliders and is valid for vertical sliders only. 


SLS_HOMETOP 
The slider uses the top of the slider as the base value for incrementing. This is 
valid for vertical sliders only. 


Specify one of the following to determine the location of the slider buttons. If you do not 
specify one of these styles, or if conflicting styles are specified, slider buttons are not 
included in the slider control. 


SLS_BUTTONSLEFT 
The slider includes incremental slider buttons with the control and places them to 
the left of the slider shaft. These slider buttons move the slider arm by one 
position, either left or right, in the direction that is selected. This is valid for 
horizontal sliders only. 


SLS_BUTTONSRIGHT 
The slider includes incremental slider buttons with the control and places them to 
the right of the slider shaft. These slider buttons move the slider arm by one 
position, either left or right, in the direction that is selected. This is valid for 
horizontal sliders only. 


SLS_BUTTONSBOTTOM 
The slider includes incremental slider buttons with the control and places them at 
the bottom of the slider shaft. These slider buttons move the slider arm by one 
position, either up or down, in the direction that is selected. This is valid for 
vertical sliders only. 


SLS_BUTTONSTOP 
The slider includes incremental slider buttons with the control and places them at 
the top of the slider shaft. These slider buttons move the slider arm by one 
position, either up or down, in the direction that is selected. This is valid for 
vertical sliders only. 


Other styles that you can specify: 


SLS_SNAPTOINCREMENT 
The slider arm, when moved to a position between two specified values on the 
slider scale, such as between two tick marks, is positioned on the nearest value 
and is redrawn at that position. If this style is not specified, the slider arm remains 
at the position to which it is moved. 


SLS_READONLY 
The slider is created as a read-only slider. This means that the user cannot 
interact with the slider. It is used merely as a mechanism to present a quantity to 
the user, such as the percentage of completion of an ongoing task. Visual 
differences for a read-only slider include a narrow slider arm, no slider buttons and 
no detents. 
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SLS_RIBBONSTRIP 


As the slider arm moves,, the slider fills the slider shaft between the home position 


and the slider arm with a color value that is different from the slider shaft color, 
similar to the mercury in a thermometer. 


SLS_OWNERDRAW 


The application is notified whenever the slider shaft, the ribbon strip, the slider 
arm, and the slider background are to be drawn. 


Slider Control Data 
See “SLDCDATA” on page A-187. 
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Slider Control Notification Messages 


These messages are initiated by the slider control window to notify its owner of significant 
events. 


WM_CONTROL (in Slider Controls) 
For the cause of this message, see WM_CONTROL. 


Parameters 
param1 


id (USHORT) 
Slider control identity. 


notifycode (USHORT) 
Notification code. 


The slider control uses these notification codes: 


SLN_CHANGE The slider arm position has changed. 
SLN_KILLFOCUS The slider control is losing the focus. 
SLN_SETFOCUS The slider control is receiving the focus. 


SLN_SLIDERTRACK _ The slider arm is being dragged, but has not been released. 


param2 


notifyinfo (ULONG) 
Control-specific information. 
When the value of the notifycode parameter is SLN_CHANGE or 
SLN_SLIDERTRACK, this value is the new arm position, expressed as the number 
of pixels from the home position. 


Otherwise, this value is the window handle (HWND) of the slider control. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The slider control window procedure generates this message and sends it to its owner, 
informing the owner of this event. 


Default Processing 
For a description of the default processing, see WM_CONTROL. 


Chapter 24. Slider Control Window Processing 24-5 


WM_CONTROLPOINTER (in Slider Controls) 
For the cause of this message, see WM_CONTROLPOINTER. 


For a description of the parameters, see WM_CONTROLPOINTER. 


Remarks 
For the appropriate remarks, see WM_CONTROLPOINTER. 


Default Processing 
For the default processing, see WM_CONTROLPOINTER. 


WM_DRAWITEM (in Slider Controls) 


If the SLS_OWNERDRAW style bit is set for a slider control, this notification message is sent 
to that slider control’s owner whenever the slider shaft, ribbon strip, slider arm, and slider 
background are to be drawn. 


Parameters 
param1 


id (USHORT) 
Window identifier. 


The window identifier of the slider control sending this notification message. 


param2 


powneritem (POWNERITEM) 
Pointer to an OWNERITEM data structure. 


The following list defines the OWNERITEM data structure fields that apply to the 
slider control. See OWNERITEM for the default field values. 


hwnd (HWND) 

Slider window handle. 
hps (HPS) 

Presentation-space handle. 
fsState (ULONG) 


Slider window style flags. See “Slider Control Styles” on page 24-1 for 
descriptions of these style flags. . 


fsAttribute (ULONG) 
Reserved. 


fsStateOld (ULONG) 
Reserved. 
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fsAttributeOld (ULONG) 
Reserved. 


rclitem (RECTL) 
Item rectangle to be drawn in window coordinates. 


idltem (LONG) 
Identity of item to be drawn: 


SDA_SLIDERSHAFT _ Specifies that the slider shaft is to be drawn. 


SDA_RIBBONSTRIP _ Specifies that the slider shaft area that contains a 
ribbon strip is to be drawn. 


SDA_SLIDERARM Specifies that the slider arm is to be drawn. 
SDA_BACKGROUND __ Specifies that the slider background is to be drawn. 


hitem (ULONG) 
Reserved. 


Returns 
re (BOOL) 
Item-drawn indicator. 


TRUE The owner draws the item. 
FALSE _ If the owner does not draw the item, the owner returns this value and the 
slider control draws the item. 


Remarks 

The slider control provides this message to give the application the opportunity to provide a 
custom slider shaft, custom ribbon strip, custom slider arm, and custom background. The 
application can specify one or all of these items and is given the opportunity to do so. 


The slider control window procedure generates this message and sends it to its owner, 
informing the owner that an item.is to be drawn. The owner is then given the opportunity to 
draw that item, and to indicate that an item has been drawn or that the slider control is to 
draw it. 


Default Processing 
‘For a description of the default processing, see WM_DRAWITEM. 
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Slider Control Window Messages 


This section describes the slider contro! window procedure actions on receiving the following 
messages. 


SLM_ADDDETENT 
This message places a detent along the slider shaft at the position specified on the primary 
scale. A detent is an indicator that represents a predefined value for a quantity. It does not 
have to correspond to an increment of the slider. 


Parameters 
param1 


usDetentPos (USHORT) 
Detent position. 


Number of pixels the detent is positioned from home. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulDetentid (ULONG) 
Detent ID. 


Unique identifier for the detent being added to the slider. If 0 is returned, an error 
occurred. The WinGetLastError function may return the following errors: 


° PMERR_HEAP_MAX SIZE_REACHED 
° PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

The application uses this message to add detents along the slider to denote values that do 
not fall along an increment setting. An example of this would be a slider that represents 
temperature and has increments that are on multiples of 5. A detent could be located at 32, 
instead of 30 or 35, for special purposes. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 
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SLM_QUERYDETENTPOS 


This message queries for the current position of a detent. 


Parameters 
param1 


ulDetentld (ULONG) 
Detent ID. 


Unique detent identifier, which indicates the position to be returned. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


usDetentPos (USHORT) 
Detent position. 


Number of pixels the detent is positioned from home. 


>=0 Number of pixels the detent is positioned 
from home. 


SLDERR_INVALID_PARAMETERS _ An error occurred. The WinGetLastError 
function may return the following error: 


PMERR_INVALID_PARAMETERS. 


fDetentLocation (USHORT) 
Scale. 


The scale along which the detent is located. One of the following: 


SMA_SCALE1 Detent position is along scale 1. 
SMA_SCALE2 __ Detent position is along scale 2. 


Remarks 
An application could use this message to place text above the detent or position an item 
relative to it. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 
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SLM_QUERYSCALETEXT 
This message queries for the text associated with a tick mark for the primary scale and 
copies that text into a buffer. ’ 


Parameters 
param1 


usTickNum (USHORT) 
Tick location. 


Tick location to query for the text. 


usBufLen (USHORT) 
Buffer length. 


Length of the buffer to copy the text into. The buffer size should include space for 
the null termination character. 


param2 


pTickText (PSZ) 
Pointer to the buffer into which to place the text string for the tick mark. 


Returns 
sTextLen (SHORT) 
Count of bytes. 


Count of bytes copied to buffer. 


>= 0 Length of the text string, excluding the null 
termination character. 


SLDERR_INVALID_PARAMETERS _ An error occurred. The WinGetLastError function 
may return the following errors: 


e PMERR_INVALID_PARAMETERS 
e PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 
This message could be used to return text that represents the current position of the slider 
arm or to query the text for use in ownerdraw mode. 


By specifying 0 as the value of the usBufLen parameter and then looking at the value 
returned in the sTextLen parameter, an application can determine the size of the buffer to 
allocate for copying the text. An application can then allocate a buffer of this size, adding 
one byte for the null termination character, and then specify this buffer and size on the query 
call. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


SLM_QUERYSLIDERINFO 


This message queries the current position or dimensions of a key component of the slider. 
The information returned and its format depends on the type of information requested. 


Parameters 
param1 


usInfoType (USHORT) 
Information attribute. 


Attribute that identifies the requested information. It can be one of the following: 


SMA_SHAFTDIMENSIONS Queries for the length and breadth of the slider 
shaft. 
SMA_SHAFTPOSITION Queries for the x-, y-position of the lower-left 


corner of the slider shaft. 


SMA_SLIDERARMDIMENSIONS = Queries for the length and breadth of the slider 
arm. 


SMA_SLIDERARMPOSITION Queries for the position of the slider arm. The 
position can be returned either as an increment 
position or a range value. 


usArmPosType (USHORT) 
Format attribute. 


Attribute that identifies the format in which the information should be returned if the 
slider arm position is requested. This value is ignored for all other queries and is 
one of the following: 


SMA_RANGEVALUE The value returned represents the number of pixels 
between the home position and the current arm 
position in the low order byte. The high order byte 
represents the pixel count of the entire range of the 
slider control. 


SMA_INCREMENTVALUE _ The value returned represents an increment position 
using the primary scale. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ullnfo (ULONG) 
Return information. 


One of the following items, depending on which SMA_* message attribute or attributes, 
were set with the SLM_SETSLIDERINFO message: 


e Ifthe SMA_SHAFTDIMENSIONS attribute is set, the following is returned: 


usShaftLength (USHORT) 
Length of the slider shaft, in pixels. It is the width of the slider shaft for 
horizontal sliders, and the height of the slider shaft for vertical sliders. 


usShaftBreadth (USHORT) 
Breadth of the slider shaft, in pixels. It is the height of the slider shaft for 
horizontal sliders, and the width of the slider shaft for vertical sliders. 


e If the SMA_SHAFTPOSITION attribute is set, the following is returned: 


xShaftCoord (USHORT) 
X-coordinate of the slider shaft position within the slider window. This value is 
expressed in window coordinates and represents the lower-left corner of the 
slider shaft. 


yShaftCoord (USHORT) 
Y-coordinate of the slider shaft position within the slider window. This value is 
expressed in window coordinates and represents the lower-left corner of the 
slider shaft. 


e Ifthe SMA_SLIDERARMDIMENSIONS attribute is set, the following is returned: 


usArmLength (USHORT) 
Length of the slider arm, in pixels. It is the width of the slider arm for horizontal 
sliders and the height of the slider arm for vertical sliders. 


usArmBreadth (USHORT) 
Breadth of the slider arm, in pixels. It is the height of the slider arm for 
horizontal sliders and the width of the slider arm for vertical sliders. 


e If the SMA_SLIDERARMPOSITION and SMA_INCREMENTVALUE attributes are 
set, the following is returned: 


usArmPos (USHORT) 
Number of pixels from the home position to the slider arm. 


usSliderRange (USHORT) 
Number of pixels over which the user could select a value on the slider. 


e If the SMA_SLIDERARMPOSITION and SMA _ INCREMENTVALUE attributes are 
set, the following is returned: 


usincrementPos (USHORT) . 
Increment that corresponds to the current position of the slider arm. 
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¢ If the SLDERR_INVALID_-PARAMETERS error is returned, an error occurred. The 
WinGetLastError function may return the following error: 


PMERR_INVALID_ PARAMETERS. 


Remarks 
The application uses this message to query for information about individual parts of a slider 
control, or the value selected by a user. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return O. 


SLM_QUERYTICKPOS 


This message queries for the current position of a tick mark for the primary scale. This 
represents where the tick mark would be located. The tick mark does not have to have a 
size (that is, to be visible) to use this message. 


Parameters 
param1 


usTickNum (USHORT) 
Tick mark location. 


Specifies the tick mark location to query for the position. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ReturnCode 


xTickPos (USHORT) 
X-coordinate. 


X-coordinate of the point that represents the position of the tick mark. It is the 
starting position of the tick mark and represents the end of the tick mark closest to 
the slider shaft. 


yTickPos (USHORT) 
Y-coordinate. 


Y-coordinate of the point that represents the position of the tick mark. It is the - 
starting position of the tick mark and represents the end of the tick mark closest to 
the slider shaft. 
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If NULL is returned in either parameter, an error occurred. The WinGetLastError 
function may return the following error: 


PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks : 

This message could be used to get the position of a tick mark along the slider for use in 
ownerdraw mode if, for example, you want to place something other than text, such as bit 
maps or icons, above the tick marks. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


SLM_QUERYTICKSIZE 


This message queries for the size of a tick mark for the primary scale. All tick marks default 
to a size of 0 (invisible) if not set by the application with the SLM _SETTICKSIZE message. 


Parameters 
param1 


usTickNum (USHORT) 
Tick mark location. 


Specifies the tick mark location to query for the size. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usTickSize (USHORT) 
Tick mark length. 


Specifies the length of the tick mark at the position queried, in pixels. If this value is 0, 
the tick mark is invisible. 


If the SLDERR_INVALID_PARAMETERS error is returned, an error occurred. The 
WinGetLastError function may return the following error: 


PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 
The application uses this message to query a scale along the slider to indicate what tick 
marks, tick mark sizes, or both are currently set for the slider. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


SLM_REMOVEDETENT 


This message removes a previously specified detent. A detent is an indicator that represents 
a predefined value for a quantity and does not have to correspond to an increment of the 
slider. 


Parameters 
param1 


ulDetentid (ULONG) 
Detent ID. 


Unique detent identifier for the detent that is to be removed from the slider. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Detent was successfully removed. 


FALSE An error occurred. The WinGetLastError function may return the following 
error: 


PMERR_INVALID_PARAMETERS. 


Remarks 
The application uses this message to remove detents added previously to the slider to 
denote values that do not fall along an increment setting. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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a SETSCALETEXT 


This message sets text above a tick mark for the primary scale. A tick mark does not have 
to be visible to have text set above it. The text is centered on the tick mark. 


Parameters 
parami1 


usTickNum (USHORT) 
Tick mark location. 


Specifies the tick mark location that is to have the text placed with it. 


param2 


pTickText (PSZ) 
Pointer to the text that is to be drawn at the position specified. 


If this value is NULL, no text is drawn. 


Returns 
re (BOOL) 
Success indicator. 


TRUE ~~ Text was successfully added to the scale. 


FALSE An error occurred. The WinGetLastError function may return the following 
errors: 


¢ PMERR_HEAP_ MAX SIZE_REACHED 
¢ PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

The application uses this message to draw text along the increments of the slider to clarify 
the magnitude of the range. This text could show the exact value for that tick mark, or could 
be a general remark, such as low, high, and so forth. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 
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SLM_SETSLIDERINFO 


This message sets the current position or dimensions of a key component of the slider. The 
component to be changed is indicated by one parameter and the new value is placed in the 
other. 


Parameters 
param1 


usinfoType (USHORT) 
Component attribute. 


Identifies the slider component that is to be modified. Specify one of the following: 


SMA_SHAFTDIMENSIONS Sets the width (for vertical sliders) or height (for 
horizontal sliders) of the slider shaft. 
SMA_SHAFTPOSITION Sets the x-, y-position of the lower-left corner of 


the slider shaft in the slider window. 
SMA_SLIDERARMDIMENSIONS _ Sets the width and height of the slider arm. 


SMA_SLIDERARMPOSITION Sets the position of the slider arm. This value 
can be specified either as an increment position 
or a range value. 


usArmPosType (USHORT) 
Format attribute. 


Identifies the format in which the information should be interpreted by the slider if 
setting the slider arm position is requested. This value is a reserved field for other 
set requests. The format is one of the following: 


SMA_RANGEVALUE Number of pixels between the home position and the 
current arm position. 


SMA_INCREMENTVALUE _ Increment position using the primary scale. 
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param2 


ullnfo (ULONG) 
New value. 


New value to change the slider component to. The format of the information 
depends on the component being changed and is indicated by the SMA_* message 
attribute or attributes that are set. 


If the SMA_SHAFTDIMENSIONS attribute is set, the u/info parameter is as 
follows: 


usShaftBreadth (USHORT) 
Width (for vertical sliders) or height (for horizontal sliders) the slider shaft 
should be set to, in pixels. This is the breadth the shaft should be. 


If the SMA_SHAFTPOSITION attribute is set, the u/info parameter is as follows: 


xShaftCoord (USHORT) 
X-coordinate to set the position of the shaft to within the slider window. 
This value is expressed in window coordinates and represents the lower-left 
corner of the shaft. 


yShaftCoord (USHORT) 
Y-coordinate to set the position of the shaft to within the slider window. 
This value is expressed in window coordinates and repieeeils the lower-left 
corner of the shaft. 


If the SMA_SLIDERARMDIMENSIONS attribute is set, the u/l/nfo parameter is 
as follows: 


usArmLength (USHORT) 
Length of the slider arm, in pixels. This is the width of the arm for 
horizontal sliders and the height of the arm for vertical sliders. 


usArmBreadth (USHORT) 
Breadth of the slider arm, in pixels. This is the height of the arm for 
horizontal sliders and the width of the arm for vertical sliders. 


If the SMA_SLIDERARMPOSITION and SMA_RANGEVALUE attributes are 
set, the ullnfo parameter is as follows: 


usArmPos (USHORT) 
Number of pixels to be set from home to the slider arm. 


If the SMA_SLIDERARMPOSITION and SMA_INCREMENTVALUE attributes 
are set, the u/info parameter is as follows: 


usincrementPos (USHORT) 
Increment value which corresponds to the position the slider arm should be 
set to. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE — Slider component was successfully set. 


FALSE Anerror occurred. The WinGetLastError function may return the following 
errors: 


e PMERR_INVALID_PARAMETERS 
e PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

The application uses this message to customize the slider for a specific use. In setting the 
shaft dimensions, only the breadth of the slider can be set. The length of the shaft is always 
determined by the number of increments and the spacing between increments, both of which 
are set for the primary scale when the slider is created. 


Positioning of the shaft within the slider window could be used by applications that cannot 
use the default positioning provided by the slider control. 


Setting of the slider arm dimensions could be used by applications that need a larger slider 
arm, such as touch screen applications. 
Setting the slider arm position can be used to: 

¢ Set the initial value of the slider before it becomes visible. 

e Change the value when it is tied to another control, such as an entry field. 


e Show the value of a quantity when the slider is being used to monitor an event, such as 
a read-only slider being used as a progress indicator. 


Default Processing 
The default window procedure does not expect to receive this message sand therefore takes 
no action on it other than to return FALSE. 


SLM_SETTICKSIZE 


This message sets the size of a tick mark for the primary scale. All tick marks are initially 
set to a size of 0 (invisible). Each tick mark along a scale can be set to the size desired. 


Parameters 
param1 


usTickNum (USHORT) 
Tick mark location. 


Tick mark location whose size is to be changed. If the SMA_SETALLTICKS 
attribute is specified for this parameter, all tick marks on the primary scale are set to 
the size specified. 
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usTickSize (USHORT) 
Tick mark length. 


Length of the tick mark, in pixels. If set to 0, the tick mark will not be drawn. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE _ Tick mark position was successfully set. 


FALSE Anerror occurred. The WinGetLastError function may return the following 
errors: 


¢ PMERR_HEAP_MAX_ SIZE_REACHED 
e PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

The application uses this message to draw a scale along the slider to indicate value positions 
in relation to the slider arm. The application can set varying lengths for different increments 
of the slider to help the user understand the magnitude of the value being set. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


WM_CHAR (in Slider Controls) 


For the cause of this message, see WM_CHAR. 


For a description of the parameters, see WM_CHAR. 


Remarks 

The slider control window procedure responds to this message by sending it to its owner if it 
has not processed the key stroke. This is the most common means by which the input focus 
is switched around the various controls in a dialog box. 


The keystrokes processed by a linear slider control are: 


Down Arrow Moves the slider arm down one increment. When the slider arm 
reaches the bottom of the slider shaft or when a horizontal slider is 
being used, the Down Arrow key has no effect. 
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Up Arrow 


Left Arrow 


Right Arrow 


Shift+Down Arrow 


Shift+Up Arrow 


Shift+Left Arrow 


Shift+Right Arrow 


Home, Ctrl+Home 


End, Ctri+End 


Moves the slider arm up one increment. When the slider arm reaches 
the top of the slider shaft or when a horizontal slider is being used, the 
Up Arrow key has no effect. 


Moves the slider arm left one increment. When the slider arm reaches 
the leftmost edge or when a vertical slider is being used, the Left Arrow 
key has no effect. 


Moves the slider arm right one increment. When the slider arm reaches 
the rightmost edge or when a vertical slider is being used, the Right 
Arrow key has no effect. 


Moves the slider arm to the next detent below the current position. If 
there are no more detents or if a horizontal slider is being used, the 
Shift+Down Arrow key combination has no effect. 


Moves the slider arm to the next detent above the current position. If 
there are no more detents or if a horizontal slider is being used, the 
Shift+Up Arrow key combination has no effect. 


Moves the slider arm to the next detent left of the current position. If 
there are no more detents or if a vertical slider is being used, the 
Shift+Left Arrow key combination has no effect. 


Moves the slider arm to the next detent right of the current position. If 
there are no more detents or if a vertical slider is being used, the 
Shift+Right Arrow key combination has no effect. 


Moves the slider arm to the home position of the slider. Pressing the 
Home key or the CtrltHome key combination when the slider arm is at 
the home position has no effect. The default home position for a slider 
is the leftmost edge for horizontal sliders and the bottom edge for 
vertical sliders. 


-Moves the slider arm to the end position of the slider. Pressing the End 


key or the CtrltEnd key combination when the slider arm is at the end 
position has no effect. The default end position for a slider is the 
rightmost edge for horizontal sliders and the top edge for vertical 
sliders. 


A circular slider control only processes left and right arrow keystrokes. These keys move the 
slider arm one increment to the left or right. 


Default Processing 
For a description of the default processing, see WM_CHAR. 
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WM_PRESPARAMCHANGED (in Slider Controls) 
For the cause of this message, see WM_PRESPARAMCHANGED. 


Parameters 
param1 


attrtype (ULONG) 
Attribute type. 


Presentation parameter attribute identity. The following presentation parameters are 
initialized by the slider control. The initial value of each is shown in the following 
list: 
PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX 
Item foreground color; used when displaying text and bit maps. This color is 
initialized to SYSCLR_WINDOWTEXT. 
. PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX 


Slider background color; used for entire control as the background. This color 
— is initialized to SYSCLR_WINDOW. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks 


The application uses this message to notify the slider that a given inherited presentation 
parameter has changed. 


Default Processing 
For a description of the default processing, see WM_PRESPARAMCHANGED. 
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WM_QUERYWINDOWPARAMS (in Slider Controls) 
For the cause of this message, see WM_QUERYWINDOWPARAMS. 


Parameters 
param1 


pwndparams (PWNDPARAMS) 
Pointer to a WNDPARAMS window parameter structure. 


This structure contains: 
status (USHORT) 
Window parameter selection. 


Identifies the window parameters that are to be set or queried. Valid values for 
the slider control are: 


WPM_CBCTLDATA Window control data length. 
WPM_CTLDATA Window control data. 


The flags in the status field are cleared as each item is processed. If the call is 
successful, the status field is 0. If any item has not been processed, the flag for 
that item is still set. 


length (USHORT) 
Length of the window text. 


text (PSZ) 
Window text. 


presparamslength (USHORT) 
Length of presentation parameters. 


presparams (PVOID) 
Presentation parameters. 


ctidatalength (USHORT) 
Length of window class-specific data. 


ctidata (PVOID) 
Window class-specific data. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion. 
FALSE _ Error occurred. 


Remarks , 

The slider contro! window procedure responds to this message by returning the information in 
the buffer provided. If this message is sent to a slider window of another process, the 
information in, or identified by, the value of the pwndparams field must be in memory shared 
by both processes. 


Default Processing 
For a description of the default processing, see WM_QUERYWINDOWPARAMS. 


WM_SETWINDOWPARAMS (in Slider Controls) 
For the cause of this message, see WM_SETWINDOWPARAMS. 


Parameters 
param1 


pwndparams (PWNDPARAMS) 
Pointer to a WNDPARAMS window parameter structure. 


This structure contains: 
status (USHORT) 
Window parameter selection. 


Identifies the window parameters that are to be set or queried. The valid value 
for the slider control is: 


WPM_CTLDATA Window control data. 


The flags in the status field are cleared as each item is processed. If the call is 
successful, the status field is 0. If any item has not been processed, the flag for 
that item is still set. 


length (USHORT) . 
Length of the window text. 


text (PSZ) 
Window text. 


presparamslength (USHORT) 
Length of presentation parameters. 


presparams (PVOID) 
Presentation parameters. 
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ctldatalength (USHORT) 
Length of window class-specific data. 


ctldata (PVOID) 
Window class-specific data. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE = Successful operation 
FALSE = Error occurred. 


Remarks 
If this message is sent to a slider window of another process, the information in, or identified 
by, the value of the pwndparams field must be in memory shared by both processes. 


Default Processing 
For a description of the default processing, see WM_SETWINDOWPARAMS. 
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Chapter 25. Circular Slider Control Window Messages 


The system-provided window procedure processes the actions on a circular control 


(WC_CIRCULARSLIDER). 


Purpose 


The circular slider control supports values set in analog rather than digital form. This control 
is intended to emulate the actual controls of stereo and video components. 


The circular slider can be used instead of a linear slider. While, at present, there are no 
particular guidelines as to when a circular slider should replace a linear slider, the circular 
slider consumes less space on the screen and, therefore, is practical to represent several 
controls in the same window. For example, for an audio attributes dialog that has volume, 
balance, bass, and treble controls, you might want to use a linear slider for the volume 
control (since it is used frequently); but to conserve space and give a more familiar 
appearance, the circular slider could be used for the balance, bass, and treble. 


Circular Slider Control Styles 


These circular slider control styles are available: 


CSS_CIRCULARVALUE 


CSS_MIDPOINT 
CSS_NOBUTTON 
‘CSS_NONUMBER 
CSS_NOTEXT 
CSS_POINTSELECT 


© Copyright IBM Corp. 1994 


Draws a circular thumb, rather than a line, for the value 
indicator. 


Makes the mid-point tick mark larger. 
Does not display value buttons. 

Does not display the value on the dial. 
Does not display title text under the dial. 


Permits the values on the circular slider to change 
immediately when dragged. 


Direct manipulation is performed by using a mouse to 
click on and drag the circular slider. There are two 
modes of direct manipulation for the circular slider. 


The default direct manipulation mode is to scroll to the 
value indicated by the position of the mouse. This could 
be important if you used a circular slider for a volume 
control, for example. Increasing the volume from 0% to 
100% too quickly could result in damage to both the 
user’s ears and the equipment. , 


The other mode of direct manipulation permits the value 
on the circular slider to change immediately when 
dragged. This mode is enabled using the 
CSS_POINTSELECT style bit. When this style is used, 
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the value of the dial can be changed by tracking the 
value with the mouse, which changes values quickly. 


CSS_PROPORTIONALTICKS Allow the length of the tick marks to be calculated asa 
percentage of the radius. 


CSS_360 Permits the scroll range to extend 360 degrees. 


CSS_360 forces the CSS_NONUMBER style on. This is 
necessary to keep the value indicator from corrupting the 
number value. 


Circular Slider Control Data 
See CSBITMAPDATA. 


Default Colors 


The following system colors are used when the system draws button controls: 


SYSCLR_BACKGROUNDCOLOR 
SYSCLR_FOREGROUNDCOLOR 


Some of these defaults can be replaced by using the following Presentation parameters in 
the application resource script file or source code: 


PP_BACKGROUNDCOLOR 
PP_BORDERCOLOR 
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Circular Slider Control Notification Messages 


These messages are initiated by the circular slider control window to notify its owner of 
significant events. 


WM_CONTROL (in Circular Slider Controls) 


This message occurs when a control has a significant event to notify to its owner. 


Parameters 
param1 


usID (USHORT) 
Control-window identity. 


The identity of the circular slider that generated the notification. 


usnotifycode (USHORT) 
Notification code. 


The notification codes that indicate what action has occurred. 


CSN_SETFOCUS This code returns a Boolean indicating 
whether the circular slider control sending 
the notification message is gaining or 
losing the focus. 


param2 contains TRUE if the control is 
gaining the focus. 


CSN_CHANGED This code is sent to notify the application 
that the circular slider value has been 
changed. 


param2 contains the new value of the 
circular slider. 


CSN_TRACKING This code is sent to notify the application 


that the circular slider is being tracked by 
the mouse. 


param2 contain the inter-media value of 
the circular slider. 
Inter-media values are not necessarily 
contiguous. 
CSN_QUERYBACKGROUNDCOLOR _ This code gives the application the 
opportunity to set the background color of 
the circular slider. CLR_* or SYSCLR_* | 
values can be returned for the background ~ 
color. 


param2 is NULL. 
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WM 
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param2 


ulnotifyspec (ULONG) 
Notify control-specific information. 


Returns 
ulReserved (ULONG) 
Reserved value. 


Remarks 
The circular slider control window procedure generates this message and sends it to its 
owner, informing the owner of this event. 


_CONTROLPOINTER (in Circular Slider Controls) 
“For the cause of this message, see WM_CONTROLPOINTER. 


For a description of the parameters, see WM_CONTROLPOINTER. 


Remarks 
For the appropriate remarks, see WM_CONTROLPOINTER. 


Default Processing 
For the default processing, see WM_CONTROLPOINTER. 


PM Programming Reference Vol il 


Circular Slider Control Window Messages 


This section describes the Circular Slider Control Window Procedure actions on receiving the 


following messages. 


CSM_QUERYINCREMENT 


This message queries the increments used to scroll the value and draw the tick marks. 


Parameters 
param1 


Scrolllncre (PUSHORT) 


The increment value added or subtracted for the value of the control when scrolling. 


param2 


Tickincr (PUSHORT) 
The increment value used to draw the tick marks. 


Returns 
re (ULONG) 
Success indicator. 


TRUE Successful completion 
FALSE — Errors occurred. 


CSM_QUERYRADIUS 


This message queries the current radius of the circular slider. 


Parameters 
param1 


uRadius (PUSHORT) 
The radius of the circular slider. 


param2 


ulReserved (ULONG) 
Reserved value. 
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Returns 
re (ULONG) 
Success indicator. 


TRUE Successful completion 
FALSE _ Error occurred. 


CSM_QUERYRANGE 


This message queries the value range of the control. 


Parameters 
param1 . 


pLow (PSHORT) 
The low range value. 


param2 


pHigh (PSHORT) 
The high range value. 


Returns 
re (ULONG) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


CSM_QUERYVALUE 


This message queries the value of the control. 


Parameters 
param1 


pValue (PSHORT) 
The value of the control. 


param2 


ulReserved (ULONG) 
Reserved value. 
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Returns 
re (U“LONG) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


CSM_SETBITMAPDATA 


This message is used to change the bit maps for the plus and minus buttons. For example, 
you might want to use left or right arrows. The optimal size for these bit maps is 10 x 10 
pels. 


Parameters 
param1 


pCSBitmapData (PCSBITMAPDATA) 
The structure defining button bit maps. 


param2 


ulReserved (ULONG) 
Reserved value. 


Returns 
re (ULONG) 
Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


Remarks 
The optimal size for these bit maps is 10 x 10 pels. Other bit maps are stretched to the 
necessary size. 


CSM_SETINCREMENT 


This message sets the scroll and tick mark increments of the control. 


Parameters 
param1 


usScrolliner (USHORT) 
Scroll increment. 


This is the number by which the current value is incremented or decremented when 
one of the circular slider control button is selected. 
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param2 


usTickincr (USHORT) 
Tick mark increment. 


This represents the number of tick marks to “skip” before drawing tick marks around 
the circular slider. 


Returns 
re (ULONG) 
- Success indicator. 


TRUE Successful completion 
FALSE — Error occurred. 


CSM_SETRANGE 


This message sets the range of values which the control sends to the application via 
CSN_TRACKING and CSN_CHANGE messages. 


Parameters 
param1 


Low (SHORT) 
The minimum value of the circular slider. 


param2 


High (SHORT) 
The maximum value of the circular slider. 


Returns 
re (ULONG) 
Success indicator. 


TRUE — Successful completion 
FALSE _ Error occurred. 
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CSM_SETVALUE 


This message sets the current value of the circular slider control. 


Parameters 
param1 


Value (SHORT) 
The new value to which to set the circular slider. 


param2 


ulReserved (ULONG) 
Reserved value. 


Returns 
rc (ULONG) 
Success indicator. 


TRUE Successful completion. 
FALSE — Error occurred. 


WM_CHAR (in Circular Slider Controls) 


For the cause of this message, see WM_CHAR. 


For a description of the parameters, see WM_CHAR. 


Remarks 

The slider contro! window procedure responds to this message by sending it to its owner if it 
has not processed the key stroke. This is the most common means by which the input focus 
is switched around the various controls in a dialog box. 

The keystrokes processed by a circular slider control are: 

Left Arrow Moves the slider arm left one increment. 

Right Arrow Moves the slider arm right one increment. 


_A circular slider control only processes left and right arrow keystrokes. These keys move the 
slider arm one increment to the left or right. 


Default Processing 
For a description of the default processing, see WM_CHAR. 
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WM_PRESPARAMCHANGED (in Circular Slider Controls) 
For the cause of this message, see WM_PRESPARAMCHANGED. 


Parameters 
param1 


attrtype (ULONG) 
Attribute type. 


Presentation parameter attribute identity. The following presentation parameters are 
initialized by the slider control. The initial value of each is shown in the following 
list: 


PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX 
Item foreground color; used when displaying text and bit maps. This color is 
initialized to SYSCLR_WINDOWTEXT. 

PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX 
Slider background color; used for entire control as the background. This color 
is initialized to SYSCLR_WINDOW. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks 
The application uses this message to notify the slider that a given inherited presentation 
parameter has changed. 


Default Processing 
For a description of the default processing, see WM_PRESPARAMCHANGED. 
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WM_QUERYWINDOWPARAMS (in Circular Slider Controls) 
For the cause of this message, see WM_QUERYWINDOWPARAMS. 


Parameters 
param1 


pwndparams (PWNDPARAMS) 
Pointer to a WNDPARAMS window parameter structure. 


This structure contains: 
status (USHORT) 
Window parameter selection. 


Identifies the window parameters that are to be set or queried. Valid values for 
the slider control are: 


WPM_CBCTLDATA _ Window control data length. 
WPM_CTLDATA Window control data. 


The flags in the status field are cleared as each item is processed. If the call is 
successful, the siatus field is 0. If any item has not been processed, the flag for 
that item is still set. 


length (USHORT) 
Length of the window text. 


text (PSZ) 
Window text. 


presparamslength (USHORT) 
Length of presentation parameters. 


presparams (PVOID) 
Presentation parameters. 


ctldatalength (USHORT) 
Length of window class-specific data. 


ctldata (PVOID) 
Window class-specific data. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion. 
FALSE — Error occurred. 


Remarks 

The slider control window procedure responds to this message by returning the information in 
the buffer provided. If this message is sent to a slider window of another process, the 
information in, or identified by, the value of the pwndparams field must be in memory shared 
by both processes. 


Default Processing 
For a description of the default processing, see WM_QUERYWINDOWPARAMS. 


WM_SETWINDOWPARAMS (in Circular Slider Controls) 
For the cause of this message, see WM_SETWINDOWPARAMS. 


Parameters 
param1 


pwndparams (PWNDPARAMS) 
Pointer to a WNDPARAMS window parameter structure. 


This structure contains: 
status (USHORT) 
Window parameter selection. 


Identifies the window parameters that are to be set or queried. The valid value 
for the slider control is: 


WPM_CTLDATA 
Window control data. 


The flags in the status field are cleared as each item is processed. If the call is 
successful, the status field is 0. If any item has not been processed, the flag for 
that item is still set. 


length (USHORT) 
Length of the window text. 


text (PSZ) 
Window text. 


presparamslength (USHORT) 
Length of presentation parameters. 


presparams (PVOID) 
Presentation parameters. 
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ctidatalength (USHORT) 
Length of window class-specific data. 


ctldata (PVOID) 
Window class-specific data. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE ~~ Successful operation 
FALSE — Error. occurred. 


Remarks 
If this message is sent to a slider window of another process, the information in, or identified 
by, the value of the pwndparams field must be in memory shared by both processes. 


Default Processing 
For a description of the default processing, see WM_SETWINDOWPARAMS. 
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Chapter 26. Value Set Control Window Processing 


This system-provided window procedure processes the actions on a value set control 
(WC_VALUESET). 


Purpose 


Like radio buttons, a value set control (WC_VALUESET window class) is a visual component 
whose specific purpose is to allow a user to select one choice from a group of mutually 
exclusive choices. However, unlike radio buttons, a value set can use graphical images (bit 
maps or icons), as well as colors, text, and numbers, to represent the items that a user can 
select. 


Even though text is supported, a value set’s primary purpose is to display choices as 
graphical images. By using graphical images in a value set, you can preserve space on the 
display screen. You can also allow the user to see exactly what is being selected instead of 
having to rely on descriptions of the choices. This allows a user to make a selection faster 
than if the user had to read a description of each choice. For example, if you want to allow a 
user to choose from a variety of patterns, you can present those patterns as value set 
choices instead of having to provide a list of radio buttons with description of each pattern. 


If long strings of data are to be displayed as choices, radio buttons should be used. 
However, for small sets of numeric or textual data information, either a value set or radio 
buttons can be used. 


The value set is designed to be customizable to meet varying application requirements, while 
providing an easy-to-use user interface component that can be used to develop products that 
conform to the Common User Access (CUA) user interface guidelines. The application can 
specify different types of items, sizes, and orientations for its value sets, but the underlying 
function of the control remains the same. For a complete description of CUA value sets, 
refer to the SAA CUA Guide to User Interface Design and the SAA CUA Advanced Interface 
Design Reference. 


Value Set Control Styles 
Value set control window styles are set when a value set window is created. 


e Set one of the following styles when creating a value set control window. You can 
override these styles by specifying VIA_BITMAP, VIA_ICON, VIA_TEXT, VIA_RGB, or 
VIA_COLORINDEX attributes for individual value set items. 


VS_BITMAP The attribute for each value set item is set to the VIA_BITMAP 
value set item attribute, which means the value set treats each 
item as a bit map unless otherwise specified. This is the 
default. Figure 26-1 on page 26-2 provides an example of a 
value set with bit maps. 
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Figure 26-1. Value Set with Bit Maps 


VS_ICON The attribute for each value set item is set to the VIA_ICON 
value set item attribute, which means the value set treats each 
item as an icon unless otherwise specified. Figure 26-2 
provides an example of a value set with icons. 


Figure 26-2. Value Set with Icons 


VS_TEXT The attribute for each value set item is set to the VIA_TEXT 
value set item attribute, which means the value set treats each 
item as a text string unless otherwise specified. Figure 26-3 on 
page 26-3 provides an example of a value set with text strings. 
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_ | Millimeters 
Centimeters 


Figure 26-3. Value Set with Text Strings 


VS_RGB 


VS_COLORINDEX 


The attribute for each value set item is set to the VIA_RGB 
value set item attribute, which means the value set treats each 
item as a RGB color value unless otherwise specified. This 
style is most often used when you need to create new colors. 
Figure 26-4 provides an example of a value set with colors. 


The attribute for each value set item is set to the 
VIA_COLORINDEX value set item attribute, which means the 
value set treats each item as an index into the logical color 
table unless otherwise specified. This style is most often used 
when the colors currently available are adequate. Figure 26-4 
provides an example of a value set with colors. 


Figure 26-4. Value Set with Colors 


e Specify one or more of the following optional window styles, if desired, by using an OR 
operator (|) to combine them with the style specified from the preceding list: 
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VS_BORDER The value set draws a thin border around itself to delineate the 


control. Figure 26-5 on page 26-4 provides an example of a 
value set with a border. 


Figure 26-5. Value Set with Border 


VS_ITEMBORDER The value set draws a thin border around each item to 
delineate it from other items. 


Note: The VS_ITEMBORDER style is useful for items that are 
hard to see, such as faint colors or patterns. 


Figure 26-6 provides an example of a value set with 
item borders. 


Figure 26-6. Value Set with Item Borders 
VS_RIGHTTOLEFT The value set interprets column orientation as right-to-left, 


instead of the default left-to-right arrangement. This means 
columns are numbered from right-to-left with the rightmost 
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VS_SCALEBITMAPS 


VS_OWNERDRAW 


Value Set Control Data 


column being 1 and counting up as you move left. Home is the 
rightmost column and end is the leftmost column. 


There is no visible difference between a value set ordered 
left-to-right and a value set ordered right-to-left. Therefore, if 
your application uses multiple value sets, the ordering of the 
items should be consistent in each value set to avoid confusing 
the user. 


Note: The VS_RIGHTTOLEFT style is used on creation of the 
control. Changing this style after creation causes 
unexpected results. 


The value set automatically scales bit maps to the size of the 
cell. If this style is not used, each bit map is centered in its cell. 
Also, if the cell is smaller than the bit map, the bit map is 
clipped to the size of the cell. 


The application is notified whenever the background of the 
value set window is to be painted. 


For information on value set control data, see the following: 


“VSCDATA’” on page A-204 
“VSDRAGINFO” on page A-205 
“VSDRAGINIT” on page A-205 
“VSTEXT” on page A-206. 
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Value Set Control Notification Messages 


These messages are initiated by the value set control window to notify its owner of significant 


events. 


WM_CONTROL (in Value Set Controls) 
For the cause of this message, see WM_CONTROL. 


Parameters 
param1 


id (USHORT) 


Value set control identity. 


notifycode (USHORT) 


Notify code. 


The value set control uses these notification codes: 


VN_DRAGLEAVE 
VN_DRAGOVER 
VN_DROP 


VN_DROPHELP 
VN_ENTER 


VN_HELP 
VN_INITDRAG 


VN_KILLFOCUS 
VN_SELECT 


VN_SETFOCUS 


The value set receives a DM_DRAGLEAVE message. 
The value set receives a DM_DRAGOVER message. 


The value set receives a DM_DROP message. The 
VN_DROP notification code is sent only when an item is 
dropped on an item that has the VIA_DROPONABLE attribute. 


The value set receives a DM_DROPHELP message. 


The user presses the Enter key while the value set window 
has the focus or double-clicks the select button while the 
pointer is over an item in the value set. _ 


The value set receives a WM_HELP message. 


The drag button was pressed and the pointer was moved while 


the pointer was over the value set control. The VN_INITDRAG 


notification code is sent only for items that have the 
VIA_DRAGGABLE attribute. 


The value set is losing the focus. 


An item in the value set has been selected and is given 
selected-state emphasis. 


The value set receives the focus. 
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param2 


notifyinfo (ULONG) 
Control-specific information. 
When the value of the notifycode parameter is VN_DRAGOVER, VN_DRAGLEAVE, 
VN_DROP, or VN_DROPHELP, this parameter is a pointer to a VSDRAGINFO 
structure. 


When the value of the notifycode parameter is VN_INITDRAG, this parameter is a 
pointer to a VSDRAGINIT structure. 


When the value of the notifycode parameter is VN_ENTER, VN_HELP, or 
VN_SELECT, this parameter contains the row and coiumn of the selection cursor. 
The low-order word contains the row index, and the high-order word contains the 
column index. 


Otherwise, this parameter is the window handle (HWND) of the value set control. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The value set control window procedure generates this message and sends it to its owner, 
informing the owner of this event. 


Default Processing 
For a description of the default processing, see WM_CONTROL. 


WM_CONTROLPOINTER (in Value Set Controls) 
For the cause of this message, see WM_CONTROLPOINTER. 


For a description of the parameters, see WM_CONTROLPOINTER. 


Remarks 
For the appropriate remarks, see WM_CONTROLPOINTER. 


Default Processing 
For the default processing, see WM_CONTROLPOINTER. 
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WM_DRAWITEM (in Value Set Controls) 
This notification message is sent to the owner of a value set control each time an item that 
has the VIA_OWNERDRAW attribute is to be drawn, or when the background of a value set 
window that has the VS_OWNERDRAW style bit is to be drawn. 


Parameters 
param1 


id (USHORT) 
Window identifier. 


The window identifier of the value set control sending this notification message. 


param2 


powneritem (POWNERITEM) 
Pointer to an OWNERITEM data structure. 


The following list defines the OWNERITEM data structure fields that apply to the 
value set control. See OWNERITEM for the default field values. 


hwnd (HWND) . 
Value set window handle. 
hps (HPS) 
-Presentation-space handle. 
fsState (ULONG) 
Value set window style flags. See “Value Set Control Styles” on page 26-1 for 
descriptions of these style flags. 
fsAttribute (ULONG) 
ltem attribute flags for the indexed item. See “VM_SETITEMATTR’ on 
page 26-19 for descriptions of these attribute flags. 


fsStateOld (U LONG) 
Reserved. 


fsAttributeOld (ULONG) 
Reserved. 


relltem (RECTL) 
ltem rectangle to be drawn in window coordinates. 


idltem (LONG) 
Identity of component to be drawn. 


VDA_BACKGROUND Specifies that a part of the value set 
background is to be drawn. 
VDA_SURROUNDING Specifies that a part of the area surrounding 


the value set is to be drawn. 
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VDA_ITEMBACKGROUND Specifies that the background of an item is to 
be drawn. 


VDA_ITEM Specifies that an entire item is to be drawn. 


hitem (ULONG) 
lf the value of the identity parameter is VDA_ITEMBACKGROUND or 
VDA_ITEM, this is the current row and column index of the item to be drawn. 
The low-order word contains the row index, and the high-order word contains 
the column index. Otherwise, this is reserved. 


Returns 
rc (BOOL) 
Item-drawn indicator. 


TRUE — The owner draws the component. 
FALSE _ If the owner does not draw the component, the owner returns this value and 
the value set contro! draws the component. 


Remarks 
The value set control draws only items that are represented in one of the formats described: 
text, color, bit maps, or icons. 


If an application uses value set controls that contain items that are not represented by the 
supported formats or requires that the emphasized attribute of an item is to be drawn ina 
special manner, the application must specify those items as VIA_LOWNERDRAW and those 
items must be drawn by the owner. 


Through this message, the application can provide a custom value set background (the area 
between the items) and customize the area surrounding the value set (the area on the top 
and right sides of the value set that is left over when the value set calculates its size). The 
application can specify how either or both of these areas are drawn and is given the 
opportunity to do so. 


The value set control window procedure generates this message and sends it to its owner, 
informing the owner that something is to be drawn. The owner is given the opportunity to 
draw and to indicate whether the value set control should continue with the normal drawing 
of that component. 


Default Processing 
For a description of the default processing, see WM_DRAWITEM. 
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Value Set Control Window Messages 


This section describes the value set control window procedure actions on receiving the 
following MgSeages: 


VM_QUERYITEM 


This message queries the contents of the item indicated by the values of the usRow and 
usColumn fields. The information returned is interpreted based on the attribute of the item. 


Parameters 
param! 


usRow (USHORT) 
Row index. 


Row index of the item to be queried. Rows have a value from 1 to the value of the 
usRowCount field. This value, which is the total number of rows in the value set, is 
specified in the VSCDATA data structure when the value set control is created. 


usColumn (USHORT) 
Column index. 


Column index of the item to be queried. Columns have a value from 1 to the value 

of the usColumnCount field. This value, which is the total number of columns in the 
value set, is specified in the VSCDATA data structure when the value set control is 

created. 


param2 


pvsText (PVSTEXT) 
Pointer to a VSTEXT data structure or NULL. 


If the attribute of the item to query is VIA_TEXT, the value of the param2 parameter 
is the same as the value of the pvsText field. For all other attributes, the param2 
‘parameter is reserved and should be set to a NULL value. 


See “VSTEXT” on page A-206 for definitions of this structure’s fields as they apply 
to the VM_QUERYITEM message. 


Returns 
ulltemid (ULONG) 
Item information. 


This value depends on the VIA_* attribute specified for the value set item. 
e Ifthe VIA_TEXT attribute is set, the following is returned: 


usTextLen (USHORT) . 
Number of bytes copied to the buffer. This is the length of the text string, 
excluding the null termination character. 
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e If the VIA_BITMAP attribute is set, the following is returned: 


hbmitem (HBITMAP) . 
Handle of the bit map associated with the item indexed by the param? 
parameter. If the item is empty, a NULL value is returned. 


e Ifthe VIA_ICON attribute is set, the following is returned: 


hptitem (HPOINTER) 
Handle of the icon associated with the item indexed by the param? parameter. 
if the item is empty, a NULL value is returned. 


e Ifthe VIA_RGB attribute is set, the following is returned: 


rgbltem (ULONG) 
Color value associated with the item indexed by the param? parameter. If the 
item is empty, a NULL value is returned. Each color value is a 4-byte integer 
with a value of: 
(R * 65536) + (G * 256) +B 
where: 


R Red intensity value 
G Green intensity value 
B Blue intensity value. 


e If the VIA_COLORINDEX attribute is set, the following is returned: 


ulColorindex (ULONG) 
Index of the color associated with the item indexed by the param? parameter. 


The following is returned for any of the items to indicate an error condition: 


VSERR_INVALID_PARAMETERS 
An error occurred. The WinGetLastError function may return the following errors: 


* PMERR_INVALID_ PARAMETERS 
¢ PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

The application uses this message to query the contents of an individual value set item. 
When querying a text item, the application must provide a buffer for returning the text 
information. By specifying 0 as the value of the usBufLen field and then getting the value 
returned in the usTextLen parameter, an application can determine how large this buffer 
must be. The value returned is the length of the text string, excluding the null termination 
character. 


Default Processing 3 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. . 
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VM_QUERYITEMATTR . 


This message queries the attribute or attributes of the item indicated by the values of the 
usRow and usColumn fields. 


Parameters 
param1 


usRow (USHORT) 
Row index. 


Row index of the item for which the attribute or attributes are queried. Rows have a 
value from 1 to the value of the usRowCount field. This value, which is the total 
number of rows in the value set, is specified in the VSCDATA data structure when 
the value set control is created. 


usColumn (USHORT) 
Column index. 


Column index of the item for which the attribute or attributes are queried. Columns 
have a value from 1 to the value of the usColumnCount field. This value, which is 
the total number of columns in the value set, is specified in the VSCDATA data 
structure when the value set control is created. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usitemAttr (USHORT) 
Item information. 


This value depends on the VIA _* attribute or attributes specified for the value set item. 


¢ One of the following attributes can be set: 


. VIA_BITMAP If this attribute is set, the item is a bit map. This is the 
default. 
VIA_COLORINDEX If this attribute is set, the item is an index into the logical 
color table. 
VIA_ICON If this attribute is set, the item is an icon. 
VIA_RGB If this attribute is set, the item is a color entry. 
VIA_TEXT If this attribute is set, the item is a text string. 
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e In addition, one or more of the following attributes can be set: 


VIA_DISABLED If this attribute is set, the item cannot be selected and is 
displayed with unavailable-state emphasis, if possible. 
Unavailable text items are always displayed with 
unavailable-state emphasis, according to CUA guidelines; 
for items displayed as color, bit maps, and icons, it is the 
application’s responsibility to determine the best way to 
show that these items are unavailable, if possible. 


The selection cursor can be moved to an unavailable item 
by using either the keyboard navigation keys or a pointing 
device. This allows a user to press the F1 key to find out 
why that item cannot be selected. 


VIA_DRAGGABLE If this attribute is set, the item can be the source of a direct 
manipulation action. 


VIA_DROPONABLE If this attribute is set, the item can be the target of a direct 
manipulation action. 


VIA_LOWNERDRAW If this attribute is set, a paint notification message is sent 
whenever this item needs painting. 


¢ The following is returned if an error occurs: 


VMERR_INVALID_PARAMETERS 
The WinGetLastError function may return the following errors: 


— PMERR_INVALID PARAMETERS 
— PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 
The application uses this message to query the specific attribute or attributes of a value set 
item. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 
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- VM_QUERYMETRICS 


This message queries for the current size of each value set item or for the spacing between 
items. The value returned is either the width and height of one item, or the spacing between 
items. 


Parameters 
param1 


fMetric (USHORT) 
Control metric. 


Control metric to be queried with this message. This can be either of the following: 


VMA_ITEMSIZE If this message attribute is set, the width and height of each 
item (in pixels) are returned in the usitemWidth and 
usltemHeight parameters, respectively. 


VMA_ITEMSPACING __ If this message attribute is set, the horizontal and vertical 
spacing between items (in pixels) is returned in the 
usHorzltemSpacing parameter and in the 
usVertitemSpacing parameter, respectively. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulMetric (U“LONG) 
Metric value queried for. 


VSERR_INVALID_ PARAMETERS 
An error occurred. The WinGetLastError function may return the following error: 
PMERR_INVALID_-PARAMETERS. 
>= 0 
This value depends on the VMA * attribute set in the param? parameter. 
¢ If the VMA_ITEMSIZE attribute is set, the following is returned: 


usltemWidth (USHORT) 
Width of one value set item, in pixels. 


usltemHeight (USHORT) 
Height of one value set item, in pixels. 
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e If the VMA_ITEMSPACING attribute is set, the iolowing is returned: 


usHorzltemSpacing (USHORT) 
Amount of horizontal space allocated between each value set item, in 
pixels. This number does not include the space needed for selected-state 
and target emphasis, and for the selection cursor, because the emphasis 
and cursor space is automatically allocated by the value set control. The 
default space amount is 0. 


usVertitemSpacing (USHORT) 
Amount of vertical space allocated between each value set item, in pixels. 
This number does not include the space needed for selected-state and 
target emphasis, and for the selection cursor, because the emphasis and 
cursor space is automatically allocated by the value set control. The 
default space amount is 0. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


VM_QUERYSELECTEDITEM 
This message queries for the currently selected value set item indicated by the values of the 
usRow and usColumn fields. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns | 
ReturnCode 


usRow (USHORT) 
Row index. 


Row index of the currently selected value set item. Rows have a value from 1 to 
the value of the usRowCount field. This value, which is the total number of rows in 
the value set, is specified in ‘the VSCDATA data structure when the value set control 
is created. 
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usColumn (USHORT) 
Column index. 


Column index of the currently selected value set item. Columns have a value from 
1 to the value of the usColumnCount field. This value, which is the total number of 
columns in the value set, is specified in the VSCDATA data structure when the 
value set contro! is created. 


Remarks 
The application uses this message to query the index of the currently selected value set 
item. If 0 is returned, no item is selected. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return 0. 


VM_SELECTITEM 


This message selects the value set item indicated by the values of the usRow and usColumn 
parameters. When a new item is selected, the previously selected item is deselected. 


Parameters 
param1 


usRow (USHORT) 
Row index. 


Row index of the value set item to select. Rows have a value from 1 to the value of 
the usRowCount field. This value, which is the total number of rows in the value 
set, is specified in the VSCDATA data structure when the value set control is 
created. 


usColumn (USHORT) 
Column index. 


Column index of the value set item to select. Columns have a value from 1 to the 
value of the usCo/umnCount field. This value, which is the total number of columns 
in the value set, is specified in the VSCDATA data structure when the value set 
control is created. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (BOOL) 
Success indicator. 


TRUE Item was successfully selected. 


FALSE An error occurred. The WinGetLastError function may return the following 
errors: 


° PMERR_INVALID_ PARAMETERS 
¢ PMERR PARAMETER_OUT_OF_RANGE. 


Remarks 
The application uses this message to select the specified value set item. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


VM_SETITEM 
This message specifies the type of information that will be contained by a value set item. 
This item is indicated by the values of the usRow and usCo/umn fields. Each value set item 
can contain a different type of information. The value set interprets the information set for 
the item based on the attribute of the item. Value set items that are not set (blank items) are 
drawn using the background color of the value set. 


Parameters 
param1 


usRow (USHORT) 
Row index. 


Row index of the value set item for which information is being specified. Rows have 
a value from 1 to the value of the usRowCount field. This value, which is the total 
number of rows in the value set, is specified in the VSCDATA data structure when 
the value set control is created. 


usColumn (USHORT) 
Column index. 


Column index of the value set item for which information is being specified. 
Columns have a value from 1 to the value of the usCo/lumnCount field. This value, 
which is the total number of columns in the value set, is specified in the VSCDATA 
data structure when the value set control is created. 
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param2 


ulltemld (ULONG) 
Item information. 


This value depends on the VIA _* attribute set for the item. | 


e Ifthe VIA_TEXT attribute is specified, the ulltemid field is as follows: 


pszitem (PSZ) 
Pointer to a null terminated string containing the text to be placed in the 
item. If NULL is passed in, the item is blank. 


e Ifthe VIA_BITMAP attribute is specified, the ulltemid field is as follows: 


hbmitem (HBITMAP) 
Handle to a bit map that is to be drawn in the item indicated by the param? 
parameter. If NULLHANDLE is passed in, the item will be blank. 


e |f the VIA_ICON attribute is specified, the ulltemid field is as follows: 


hptltem (HPOINTER) 
Handle to the icon that is to be drawn in the item indicated by the param? 
parameter. If NULLHANDLE is passed in, the item is blank. 


e If the VIA_RGB attribute is specified, the ulltemid field is as follows: 


rgbltem (ULONG) 
Color value to be drawn in the item indicated by the param? parameter. If 
an invalid value is passed in (a value greater than OxOOFFFFFF), the item is 
blank. Each color value is a 4-byte integer with a value of: 


(R * 65536) + (G * 256) +B 
where: 


R_ Red intensity value 
G Green intensity value 
B Blue intensity value. 


e If the VIA.COLORINDEX attribute is specified, the u/ltemid field is as follows: 


ulColorindex (ULONG) 
Index of the color in the logical color table to be drawn in the item indicated 
by the param? parameter. 


Returns 
re (BOOL) 
Success indicator. 
TRUE Item was successfully set. 


FALSE An error occurred. The WinGetLastError function may return the following 
errors: 


¢ PMERR_INVALID PARAMETERS 
* PMERR-PARAMETER_OUT_OF_RANGE. 
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Remarks 

The application uses this message to set the contents of an individual value set item. To set 
the values for the entire value set, an application would loop through the rows and columns, 
setting the value of each item during the initial value set window processing before the: 
window becomes visible. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


VM_SETITEMATTR 


This message sets the attribute or attributes of the item indicated by the values of the usRow 
and usColumn parameters. 


Parameters 
param1 


usRow (USHORT) 
Row index. 


Row index of the value set item for which attributes are being specified. Rows have 
a value from 1 to the value of the usRowCount field. This value, which is the total 
number of rows in the value set, is specified in the VSCDATA data structure when 
the value set control is created. 


usColumn (USHORT) 
Column index. 


Column index of the value set item for which attributes are being specified. 
Columns have a value from 1 to the value of the usColumnCount field. This value, 
which is the total number of columns in the value set, is specified in the VSCDATA 
data structure when the value set control is created. 


param2 


usitemAttr (USHORT) 
Item attributes. 


Attribute or attributes of the item to be set or reset based on the value of the fSet 
field. These attributes can be as follows: 


¢ One of the following attributes can be set: 


VIA_BITMAP If this attribute is set, the item is a bit map. This is the 
default. 


VIA_COLORINDEX If this attribute is set, the item is an index into the 
logical color table. 


VIA_ICON If this attribute is set, the item is an icon. 
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VIA_RGB If this attribute is set, the item is a color entry. 
VIA_TEXT If this attribute is set, the item is a text string. 
e In addition, one or more of the following attributes can be set: 


VIA_DISABLED If this attribute is set, the item cannot be selected and 
is displayed with unavailable-state emphasis, if 
possible. Unavailable text items are always displayed 
with unavailable-state emphasis, according to CUA 
guidelines; for items displayed as color, bit maps, and 
icons, it is the application’s responsibility to determine 
the best way to show that these items are unavailable, 
if possible. 


The selection cursor can be moved to an unavailable 
item by using either the keyboard navigation keys or a 
pointing device. This allows a user to press the F1 
key to find out why that item cannot be selected. 


* VIA_DRAGGABLE If this attribute is set, the item can be the source of a 
direct manipulation action. 


VIA_DROPONABLE If this attribute is set, the item can be the target of a 
direct manipulation action. 


VIA_OWNERDRAW If this attribute is set, a paint notification message is 
sent whenever this item needs painting. 


fSet (USHORT) 
Set or reset flag. 


TRUE Set the attribute of the indicated item. 
FALSE Turn off the attribute of the indicated item. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Attribute or attributes were set successfully. 

FALSE An error occurred. The WinGetLastError function may return the following 
errors: 
e PMERR_INVALID-PARAMETERS 
e PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

The application uses this message to either set or reset a specific attribute or attributes of a 
value set item. This provides customization of a control at the item level, so that applications 
can provide their own types of items with a value set, as well as perform direct manipulation 
and other actions. 
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Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


VM_SETMETRICS 


This message sets the size of each item in the value set control, the spacing between items, 
or both. 


Parameters 
param1 


fMetric (UVSHORT) 
Units of measurement. 


Unit or units of measurement that are to be set for the value set control. This can 
be either of the following: 


VMA_ITEMSIZE If this message attribute is set, the width and height of each 
item is set using the values of the us/temWidth and 
usltemHeight parameters, respectively. 


VMA_ITEMSPACING _ If this message attribute is set, the horizontal and vertical 
spacing between each item is set using the values of the 
usHorzltemSpacing and usVertltemSpacing parameters, 
respectively. 


param2 


ulltemid (ULONG) 
Item information. 


This value depends on the VMA_* attribute set for the message. 
e Ifthe VMA_ITEMSIZE attribute is specified, the ul/temid field is as follows: 


usltemWidth (USHORT) 
Width to be set for each value set item, in pixels. The number of pixels 
specified cannot be less than 2. 


usltemHeight (USHORT) 
Height to be set for each value set item, in pixels. The number of pixels 
specified cannot be less than 2. 


e If the VMA_ITEMSPACING attribute is specified, ullternid field is as follows: 


usHorzltemSpacing (USHORT) 
Amount of horizontal space to be set between each value set item, in 
pixels. This number does not include the space needed for selected-state 
and target emphasis, and for the selection cursor, because the emphasis 
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and cursor space is automatically set by the value set control. The default 
spacing is 0. 


usVertitemSpacing (USHORT) 
Amount of vertical space to be set between each value set item, in pixels. 
This number does not include the space needed for selected-state and 
target emphasis, and for the selection cursor, because the emphasis and 
cursor space is automatically set by the value set control. The default 
spacing is 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Item size or spacing was successfully set. 


FALSE Anerror occurred. The WinGetLastError function may return the following 
errors: 


¢ PMERR_INVALID_ PARAMETERS 
* PMERR_PARAMETER_OUT_OF_RANGE. 


Remarks 

Upon receiving this message, the value set redraws the control with the new width, height, 
and spacing specifications for each item. Any items that do not fit within the current window 
size are clipped. 


When the value set control receives a WM_SIZE (in Value Set Controls) message, which is 
sent when the value set window is resized, the value set control defaults the size of each 
item by dynamically dividing the window size by the number of rows and columns. It allows 
enough room for the border, selection cursor, and selection emphasis, and defaults the 
spacing between items to 0. To override these default settings, the application must resend 
the VM_SETMETRICS message. 


Default Processing 
The default window procedure does not expect to receive this message and therefore takes 
no action on it other than to return FALSE. 


WM CHAR (in Value Set Controls) 
For the cause of this message, see WM_CHAR. 


For a description of the parameters, see WM_CHAR. 


Remarks | 

The value set control window procedure responds to this message by sending it to its owner 
if it has not processed the key stroke. This is the most common means by which the focus 
is switched from one control to another in a value set window. 
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The keystrokes processed by a value set control are: 


Key Name 


Down Arrow 
Up Arrow 
Left Arrow 
Right Arrow 


Home 

End 

PgDn 
PgUp 
Ctrl+Home 
Ctri+End 


Enter 


(Mnemonic) 


Action Performed 


Moves the selection cursor down one item. When the selection cursor 
reaches the bottom, the Down Arrow has no effect. 


Moves the selection cursor up one item. When the selection cursor 
reaches the top, the Up Arrow has no effect. 


Moves the selection cursor left one item. When the selection cursor 
reaches the leftmost column, the Left Arrow has no effect. 


Moves the selection cursor right one item. When the selection cursor 
reaches the rightmost column, the Right Arrow has no effect. 


Moves the selection cursor to the leftmost column of the value set control 
(NLS dependent). Pressing the Home key when the leftmost column is 
selected has no effect. The row index does not change. 


Moves the selection cursor to the rightmost column of the value set control 
(NLS dependent). Pressing the End key when the rightmost column is 
selected has no effect. The row index does not change. 


Moves the selection cursor to the bottom row of the value set control. 
Pressing the Page Down key when the bottom row is selected has no 
effect. The column index does not change. 


Moves the selection cursor to the top row of the value set control. 
Pressing the Page Up key when the top row is selected has no effect. 
The column index does not change.  & 


Moves the selection cursor to the item in the top row and leftmost column 
of the value set control (NLS dependent). Pressing the Ctrl+Home keys 
when the top row and leftmost column is selected has no effect. 


Moves the selection cursor to the bottom row and rightmost column of the 
value set control (NLS dependent). Pressing the CtrltEnd keys when the 
bottom row and rightmost column is selected has no effect. 


Sends a VN_ENTER notification code to the owner of the value set with 
the row and column indices of the selected item. 


if the VS_TEXT style bit is set for the value set, any mnemonics specified 
can be used to select an item. 


Default Processing 
For a description of the default processing, see WM_CHAR. 
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WM_PRESPARAMCHANGED (in Value Set Controls) 
For the cause of this message, see WM_PRESPARAMCHANGED. 


Parameters 
param1 


attrtype (ULONG) 
Attribute type. 


Presentation parameter attribute identity. The following presentation parameters are 
initialized by the value set control. The initial value of each is shown in the following 
list: 


PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX 
Item foreground color; used when displaying text and bit maps. This color is 
initialized to SYSCLR_WINDOWTEXT. 


PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX 
Value set background color; used for entire control as the background. This 
color is initialized to SYSCLR_WINDOW. 


PP_HILITEBACKGROUNDCOLOR or PP_HILITEBACKGROUNDCOLORINDEX 
Selection color; this is the color used for selected-state and target emphasis. 
This color is initialized to SYSCLR_HILITEBACKGROUND. 


PP_BORDERCOLOR or PP_BORDERCOLORINDEX 
Value set and item border color. This color is initialized to 
SYSCLR_WINDOWFRAME. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The application uses this message to notify the value set that a given inherited presentation 
parameter has changed. 


Default Processing 
For a description of the default processing, see WM _PRESPARAMCHANGED. 


& 
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WM_QUERYWINDOWPARAMS (in Value Set Controls) 
For the cause of this message, see WM_QUERYWINDOWPARAMS. 


Parameters 
param1 


wndparams (PWNDPARAMS) 
Pointer to a WNDPARAMS window parameter structure. 


See WNDPARAMS for descriptions of the default fields. For a value set, the valid 
values for the fsStatus field are WPM_CBCTLDATA and WPM_CTLDATA. 


The flags in the fsStatus field are cleared as each item is processed. If the call is 
successful, the fsStatus field is NULL. If any item has not been processed, the flag 
for that item is still set. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE = Successful operation. 
FALSE — Error occurred. 


Remarks 

The value set control window procedure responds to this message by returning the 
information in the buffer provided. If this message is sent to a value set window of another 
process, the information in, or identified by, the wndparams parameter must be in memory 
shared by both processes. 


Default Processing 
For a description of the default processing, see WM_QUERYWINDOWPARAMS. 
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WM_SETWINDOWPARAMS (in Value Set Controls) | 
For the cause of this message, see WM_SETWINDOWPARAMS. 


Parameters 
param1 


wndparams (PWNDPARAMS) 
Pointer to a WNDPARAMS structure. 


See WNDPARAMS for descriptions of the fields. For a value set, the valid value of 
the fsStatus field is WPM_CTLDATA. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful operation 
FALSE Error occurred. 


Remarks 
If this message is sent to a value set window of another process, the information in, or 
identified by, the wndparams parameter must be in memory shared by both processes. 


Default Processing 
For a description of the default processing, see WM_SETWINDOWPARAMS. 


WM_SIZE (in Value Set Controls) 


For the cause of this message, see WM_SIZE. 


For a description of the parameters, see WM_SIZE. 


Remarks ; 
When the value set window is sized, the value set contro! defaults the size of each item by 
dynamically dividing the window size by the number of rows and columns. It allows enough 
room for the border, selection cursor, and selection emphasis, and defaults the spacing 
between items to 0. To override these default settings, the application must resend the 
VM_SETMETRICS message. 
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Default Processing 
For a description of the default processing, see WM_SIZE. 
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Chapter 27. Clipboard Messages 


Purpose 
The clipboard is used by the end-user to transfer data between Presentation Manager* (PM*) 
applications using the following operations: 


Cut Remove from a window, leaving a gap in the source, and save for later use. 
Copy Copy from a window, leaving the source intact, and save for later use. 
Paste Paste the cut or copied data into the window of an application (the target). 


WM_DESTROYCLIPBOARD 
This message is sent to the clipboard owner when the clipboard is emptied through a call to 
WinEmptyClipbrd. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
If there is any data that has been set with the CFl_OWNERFREE flag, the clipboard owner 
must release the data at this time. 


Default Processing 
None. 
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WM_DRAWCLIPBOARD 


This message is sent to the clipboard viewer window whenever the contents of the clipboard 
change; that is, as a result of the WinCloseClipbrd function following a call to 
WinSetClipbrdData. 


Parameters 
param 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
None. 


WM_HSCROLLCLIPBOARD 


This message is sent to the clipboard-owner window when the clipboard contains a data 
handle for the CFl OWNERDISPLAY format, and there is an event in the clipboard viewer's 
horizontal scroll bar. 


Parameters 
param1 


hwndViewer (HWND) 
Handle. 


This contains a handle to the clipboard application window. 


param2 


sposScroll (SHORT) 
Scroll position. 


The position is either: 


0 scodeScroll is other than SB_SLIDERPOSITION 
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Other The position of the slider when scodeScroll is SB_SLIDERPOSITION. 


scodeScroll (SHORT) 
Scroll-bar code. 


This is one of the SB_* scroll-bar codes as defined in WM_HSCROLL (in Horizontal 


Scroll Bars). 


SB_LINELEFT 
SB_LINERIGHT 
SB_PAGELEFT 
SB_PAGERIGHT 
SB_SLIDERPOSITION 
SB_SLIDERTRACK 


SB_ENDSCROLL 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 


Sent if the operator clicks the left arrow of the scroll bar, 
or presses the VK_LEFT key. 


Sent if the operator clicks the right arrow of the scroll bar, 
or presses the VK_RIGHT key. 


Sent if the operator clicks the area to the left of the slider, 
or presses the VK_PAGELEFT key. 


Sent if the operator clicks the area to the right of the 
slider, or presses the VK_PAGERIGHT key. 


Sent to indicate the final position of the slider. sposScroll 
contains the final position of the slider. 


Sent every time the slider position changes if the operator 
moves the scroll bar slider with the pointer device. 


Sent when the operator has finished scrolling, but only if 
the operator has not been doing any absolute slider 
positioning. 


The clipboard owner is responsible for displaying the clipboard contents. The clipboard 
owner should use WinInvalidateRect or repaint as desired. The scroll-bar position is also 


reset. 


- Default Processing 
None. 
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WM_PAINTCLIPBOARD 
This message is sent when the clipboard contains a data handle with the 
CFl_OWNERDISPLAY information flag set. 


Parameters 
param! 


hwndViewer (HWND) 
Handle. 


This is a handle to the clipboard application window. 


param2 


‘ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks — 

As the clipboard owner is responsible for displaying the clipboard contents, this message 
notifies the clipboard application that its client area needs repainting. The 
WM_PAINTCLIPBOARD message is sent to the owner of the clipboard to request repainting 
of all or part of the client area of the clipboard application. 


Note: To determine whether the entire client area needs repainting or just a portion of it, the 
clipboard owner must compare the dimensions of the drawing area to the dimensions 
given in the most recent WM_SIZECLIPBOARD message. 


Default Processing 
None. 


WM_RENDERALLFMTS 


_ This message is sent to the application that owns the clipboard while the application is being 
destroyed. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


27-4 PM Programming Reference Vol II 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The application renders the clipboard data in all formats it is capable of generating and 
passes a handle to each format to WinSetClipbrdData. This ensures that the data in the 
clipboard can be rendered even though the application has been destroyed. 


Default Processing 
None. 


WM_RENDERFMT 


This message is a request to the clipboard owner to render the data of the format specified 
in usfmt. | 


Parameters 
param1 


usfmt (USHORT) 
Data format. 


This is the format of the data to be rendered. 

CF_BITMAP A bit map. 

CF_DSPBITMAP A bit-map representation of a private data format. 
CF_DSPMETAFILE A metafile representation of a private data format. 


CF_DSPTEXT A textual representation of a private data format. 
CF_METAFILE A metafile. 
CF_TEXT An array of text characters. 

param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
ulReserved (ULONG) | 
Reserved value, should be 0. 


Remarks | : 
The data is rendered into a global handle, which is then set into the clipboard with 
WinSetClipbrdData. 


Default Processing 
None. 


WM_SIZECLIPBOARD 


This message is sent when the clipboard contains a data handle for the 
CFl_OWNERDISPLAY format, and the clipboard application window has changed size. 


Parameters 
param1 


hwndViewer (HWND) 
Handle of viewer window. 


param2 


ppaint (PRECTL) 
Rectangle to be re-painted. 


-Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The default window procedure takes no action on this message except to set u/Reserved to 
0. 
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WM_VSCROLLCLIPBOARD 


This message is sent to the clipboard owner window when the clipboard contains a data 
handle for the CFl_OWNERDISPLAY format, and there is an event in the clipboard viewer’s 


vertical scroll bar. 


Parameters 
param1 


hwndViewer (HWND) 
Handle. 


This contains a handle to the clipboard application window. | 


param2 


sposScroll (SHORT) 
Scroll position. 


The position is either: 


0 scodeScroll is other than SB_SLIDERPOSITION 
Other The position of the slider when scodeScroll is SB_SLIDERPOSITION. 


scodeScroll (SHORT) 
Scroll-bar code. 


This is one of the SB_* scroll-bar codes as defined in WM_HSCROLL (in Horizontal 


Scroll Bars). 


SB_LINELEFT 
SB_LINERIGHT 
SB_PAGELEFT 
SB_PAGERIGHT 
SB_SLIDERPOSITION 
SB_SLIDERTRACK 


SB_ENDSCROLL 


Sent if the operator clicks the left arrow of the scroll bar, 
or depresses the VK_LEFT key. 


Sent if the operator clicks the right arrow of the scroll bar, 
or depresses the VK_RIGHT key. 


Sent if the operator clicks the area to the left of the slider, 
or depresses the VK_PAGELEFT key. 


Sent if the operator clicks the area to the right of the 
slider, or depresses the VK_PAGERIGHT key. 


Sent to indicate the final position of the slider. sposScroll 
contains the final position of the slider. 


Sent every time the slider position changes if the operator 
moves the scroll bar slider with the pointer device. 


Sent when the operator has finished scrolling, but only if 
the operator has not been doing any absolute slider 
positioning. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The clipboard owner is responsible for displaying the clipboard contents. The clipboard 
owner should use WinInvalidateRect or repaint as desired. The scroll bar position is also 
reset. 


Default Processing 
None. 
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Chapter 28. Direct Manipulation (Drag) Messages 


Purpose 
This section describes the processing that occurs during a direct manipulation operation 
when the application sends or receives a direct manipulation (DM_*) message. 


DM_DISCARDOBJECT 
This message is sent to a source that supports the “DRM_DISCARD?” rendering method. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure representing the items to be discarded. 


mpparam2 


ulReserved (MPARAM) 
Reserved value, should be NULL. 


Returns 
ulAction (ULONG) 
Flag. 


DRR_SOURCE _ The source window procedure accepts responsibility for the operation. 


DRR_TARGET _ The target window procedure is to accept responsibility for the 
operation. The OS/2 shell supports the discarding of dragitems that 
can be rendered by the DRM_OS2FILE method. 


DRR_ABORT Abort the entire DM_DROP action. 


Remarks 

This message is sent to the source window for the drag action. The source should make a 
copy of the parameters and return. The source should also create a separate thread to 
execute the discard action if it responds with DRR_SOURCE. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action on it, other than to set u/Action to the default value of NULL. 
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DM_DRAGERROR 


This message is sent to the caller of DrgDragFiles or DrgAcceptDroppedFiles when an error 
occurs during a move or copy operation for a file. 


Parameters 
param1 


usError (USHORT) 
Error code. 


Returned from DosCopy, DosMove, or DosDelete. 


usOperation (USHORT) 
Flag. 


Flag indicating the operation that failed. 


DFF_MOVE DosMove failed. 
DFF_COPY DosCopy failed. 
DFF_DELETE DosDelete failed. 


param2 


hstr (HSTR) 
HSTR of file contributing to the error. 


Returns 
hstrAction (HSTR) 
Action indicator. 


DME_IGNORECONTINUE _ Do not retry the operation, but continue with the rest of the 


files. 
DME_IGNOREABORT Do not retry the operation, and do not try any other files. 
DME _-RETRY Retry the operation. 
DME_REPLACE ~ Replace the file at the destination. Used if FALSE is not 
specified. 
Other HSTR of new file name to use for retry. 


Remarks 
The receiver of this message should return the action that the sender should take. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return FALSE. 
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DM_DRAGFILECOMPLETE 


This message is sent when a direct manipulation operation on a file or files is complete. 


Parameters 
param1 


hstr (HSTR) 
File handle. 


param2 


usOperation (USHORT) 


Flags. 

DF_MOVE The operation was a move. If this flag is not set, the 
operation was a copy. 

DF_SOURCE The receiving window was the source of the drag. If this flag 


is not set, the receiver was the target of the drop. 


DF_SUCCESSFUL The drag operation was successful for the file. If this flag is 
not set, the operation failed. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks . 
hstr is HSTR for the source file if this message is sent by DrgDragFiles, and is HSTR for the 
target file if this message is sent by DrgAcceptDroppedFiles. 


This message is sent by DrgDragFiles to its caller when the move or copy operation is 
completed, regardless of success or failure. It is also sent by DrgAcceptDroppedFiles when 
a file has been successfully dropped on the caller. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. 
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DM_DRAGLEAVE 


This message is sent to a window that is being weages over when one of tiiese conditions 
occur: 


¢ The object is dragged outside the boundaries of the window. 
e The drag operation is terminated while the object is over the window. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure for the drag operation. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) _ 
Reserved value, should be 0. 


Remarks 

This message allows fei target emphasis and de-emphasis during the direct manipulation 
process. This message is not sent when a drop occurs. Use DM_DROP as a signal to 
remove the target emphasis. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action on it other than to return 0. 


DM_DRAGOVER 


"This message allows the window under the mouse pointer to determine if the object or 
objects currently being dragged can be dropped. 


param2 is the pointing device pointer location. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure representing the object being dragged 


28-4 PM Programming Reference Vol II 


param2 


sxDrop (SHORT) 


X-coordinate of the pointing device pointer in desktop coordinates. 


syDrop (SHORT) 


Y-coordinate of the pointing device pointer in desktop coordinates. 


Returns 
ReturnCode 


usDrop (USHORT) 
Drop indicator. 


DOR_DROP 


DOR_NODROP 


DOR_NODROPOP 


DOR_NEVERDROP 


usDefaultOp (USHORT) 


Object can be dropped. When this reply is given, 
usDefaultOp must be set to indicate which operation is 
performed if the user should drop at this location. 


- Object cannot be dropped at this time. The target can 


accept the object in the specified type and format using the 
specified operation, but the current state of the target will not 
allow it to be dropped on. The target may change state in 
the future so that the same object may be acceptable. 


Object cannot be dropped at this time. The target can 
accept the object in the specified type and format, but the 
current operation is not acceptable. A change in the drag 
Operation may change the acceptability of the object. 


Object cannot be dropped. The target cannot accept the 
object now and will not change state so that the object will 
be acceptable in the future. If this response is returned, no 
more DM_DRAGOVER messages will be sent to the target 
until the pointer is moved out of and back into the target 
window. 


Target-defined default operation. 


DO_COPY Operation is a copy. 
DO_LINK Operation is a link. 
DO_MOVE Operation is a move. 


Other Operation is defined by the application. 
This value should be greater than or equal to (>=) DO_UNKNOWN. 
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Remarks 
This message is sent to the window that is directly under the hot spot of the mouse pointer 
during the drag operation when any of the following conditions are met: 


e The user moves the mouse. 

e A key is pressed. 

¢ AWM_BUTTON1UP, WM_BUTTON2UP, WM _BUTTON3UP, or WM_ENDDRAG — 
message is received. The message corresponds to vkTerminate parameter specified by 
the call to DrgDrag indicating that the drag is ending. In this case the message is sent 
only if the mouse has moved since the last DM_DRAGOVER message was sent. 


The receiver can gain access to the DRAGINFO structure with DrgAccessDraginfo. The 
acceptability of the dragged objects can be determined by querying the hstrType and 
hstrRMF string handles in each of the DRAGITEM structures carried in DRAGINFO structure. 
In order to accept the drop, the target window must be able to accept ail of the objects that 
are being dragged. 


The receiver should provide target emphasis for itself. The receiver can use 
DrgSetDragPointer to change the bit map while it is being dragged over. A 
DM_DRAGLEAVE or DM_DROP message will be sent to the target in the future. Target 
emphasis should be removed at that time. 


If usOperation in DRAGINFO is DO_DEFAULT or DO_UNKNOWN and the target returns 
DOR_DROP for usDrop, usDefaultOp should be set to reflect what the target defines as the 
default operation. This information is used to provide the appropriate modification to the drag 
pointer and the target’s default operation will be passed in the usOperation field of the 
DRAGINFO structure specified in the DM_DROP message. 


If the value of the usOperation field is not DO_DEFAULT or DO_UNKNOWN, the 
usDefaultOp parameter is ignored. 


_ Note: Lazy drag enabled applications are expected to process this message. It is to be 
handled in the same manner as the standard drag enabled applications. 


Default Processing | 
The WinDefWindowProc function returns DOR_NEVERDROP to the sender of this message. 
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DM_DRAGOVERNOTIFY 
This message is sent to the source of a drag operation immediately after a DM_DRAGOVER 
message is sent to a target window. 


_ param2 is the target’s reply to the DM_DRAGOVER message. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure that represents the object being dragged. 


param2 
Target's reply. 


usDrop (USHORT) 
Drop indicator. 


usDefaultOp (USHORT) 
Default operation. 


Target-defined default operation. 


Returns 
ulReserved (ULONG) 
Reserved value. 


Remarks 
The source window can use this message to modify its behavior or appearance based on a 
target window’s response to the DM_DRAGOVER message. 


See DM_DRAGOVER for a description of the target window’s possible responses. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and therefore 
_ takes no action on it other than to return NULL. 
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DM_DROP 


This message is sent to the target when the dragged object is dropped. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

This message is sent to the target window directly under the hot spot of the mouse pointer at 
the completion of a direct-manipulation operation only if DOR_DROP was returned for the 
DM_DRAGOVER message sent to the target window during the drag. 


The receiver can obtain access to DRAGINFO structure with DrgAccessDraginfo. 


The receiver must immediately remove any target emphasis and post a private message to 
itself to initiate the data transfer conversations needed to complete the operation. 


The receiver can use the cxOffset and cyOffset fields in the DRAGITEM structure to position 
the dropped object within its window relative to the drop point. Multiple objects are moved in 
the same relative position to each other in the target window as they were in the source. 


With standard drag, DrgDrag does not return until the drag set is dropped on a target 
window. Since the source window is the caller of the DrgDrag, it receives the handle of the 
target window that the drag set is dropped on when DrgDrag returns. 


' Lazy Drag is slightly different. Since the drag operation is non-modal, the DrgLazyDrag 
returns as soon as it has completed its initialization of the drag. DM_DROPNOTIFY is 
posted to the source window after the drag set is dropped. 


When the application receiving the DM_DROP message has finished all data transfer 
operations, the target window must free the DRAGINFO structure using DrgFreeDraginfo. 
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Default Processing 
The WinDefWindowProc function calls DrgDeleteDraginfoStrHandles and DrgFreeDraginfo for 
pDraginfo and returns 0. 


DM_DROPHELP 


This message requests help for the current drag operation. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure used in the drag operation. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns . 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message is posted to the target of a drop when F1 is pressed during a 
direct-manipulation operation, and the drag operation is canceled. 


The usOperation field of pDraginfo can be used to provide help information in the context of 
the drag operation during which it was requested. 


The DM_DROPHELP message is not supported for lazy drag operations. Since the drag 
operation is non-modal, the user may request help on anything at any time during the drag. 
If the application wishes to provide drop help, it must specify the action required to invoke 
drop help (for example a menu choice), and code the support for it explicitly. 


Default Processing 
The WinDefWindowProc function calls DrgDeleteDraginfoStrHandles and DrgFreeDraginfo for 
pDraginfo and returns 0. 
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DM_DROPNOTIFY 


This message provides the source window with the target window handle and a pointer to 
the DRAGINFO structure allocated by the source window. 


Parameters 
param1 


pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure allocated by the source window receiving the 
message. 


param2 


hwndTarget (HWND) 
Handle of the target window that the drag set was dropped on. 


Note: If hwndTarget is equal to zero, the drag is canceled, and the drag set is not 
dropped. DrgCancelLazyDrag posts a DM_DROPNOTIFY message with an 
hwndTarget value of zero to the source window. 


Returns 
returns 


ulReserved (ULONG) 
Reserved value, must be 0. 


Remarks : 
This message is posted to the source window involved in the drag operation when the drag 
set is dropped on a valid target window. 


The source window must examine hwndTarget to determine if the target window is the same 
as the source window. If it is not, the source window must immediately free the DRAGINFO; 
if the source and target windows are the same, the DRAGINFO must be freed by the target 
window after completing the post-drop conversation. 


Note: Lazy drag enabled applications are expected to process this message; standard drag 
applications are not. 


Default Processing 
The default message procedure sets ulReserved to 0. 
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DM_EMPHASIZETARGET 


This message is sent to the caller of DrgAcceptDroppedFiles to inform it to either apply or 
remove target emphasis from itself. 


Parameters 
param1 


sx (SHORT) 
X-coordinate. 


X-coordinate of the pointing device pointer in window coordinates. 


sy (SHORT) 
Y-coordinate. 


Y-coordinate of the pointing device pointer in window coordinates. 


usparam2 


usEmphasis (USHORT) 
Flags. 


TRUE Apply emphasis. 
FALSE Remove emphasis. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. 


DM_ENDCONVERSATION 


The target uses this message to notify a source that a drag operation is complete. 


Parameters 
param1 


ulltemiD (ULONG) 
Item ID. 


The ulltem!D from the DRAGITEM that was contained within the DRAGINFO 
structure when the object was dropped. 
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-param2 


ulFlags (ULONG) 
Flags. 


The flags are set as follows: 


DMFL_TARGETSUCCESSFUL The target successfully completed its portion of 
the rendering operation. 


DMFL_TARGETFAIL The target failed to complete its portion of the 
rendering operation. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
This message is used to inform a source that the target has completed its part of a rendering 
operation. It is sent by the target to the source. 


The target must send this message under any of the following circumstances: 


¢ The target receives a DM_RENDERCOMPLETE message and will not retry the 
operation. 

e The target completes the rendering operation without involvement from the source. 

¢ The target wants to terminate a rendering operation in progress. 

e The target chooses not to render an object that was dropped on it. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. . 


DM_FILERENDERED 


This message is sent to the window handling the drag conversation for the caller of 
DrgDragFiles. 


Parameters 
param1 


rndf (PRENDERFILE) 
Pointer to a RENDERFILE structure. 
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param2 


usOperation (USHORT) 
Flags. 


TRUE Operation succeeded 
FALSE Operation failed. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

This message is sent when the rendering (moving or copying) of a file is complete. The 
handle of this window is the hwndDragFiles field of the RENDERFILE structure sent on 
DM_RENDERFILE. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. 


DM_PRINTOBJECT 


This message is sent to a source that supports the “DRM_PRINT” rendering method when 
objects are dropped on a printer object. 


Parameters 
param1 


pDraginfo (PDRAGINFO) . 
Pointer to the DRAGINFO structure representing the objects to be printed. 


param2 


pPrintDest (PPRINTDEST) 
Pointer to the PRINTDEST structure representing printer object to print to. 


The structure contains all the parameters required to call the functions 
DevPostDeviceModes and DevOpenDC. 
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Returns 
ulAction (ULONG) 
Flag. 


DRR_SOURCE The source window procedure/object procedure will take responsibility 
for the print operation. 


DRR_TARGET _ The target printer object will take responsibility for the print operation 
(this will only work on objects which are of the pre-registered 
rendering method; “DRM_OS2FILE.” 


DRR_ABORT Abort the entire DM_DROP action (do not send any more 
DM_PRINTOBJECT messages to any selected source object involved 
in this DM_DROP. 


Remarks 

This message is sent to the source window procedure. The source window procedure is 
responsible for interpreting the structure given by param2. It should make a copy of all the 
parameters and then return. 


The receiver of this message should create a thread in which to dispatch this message in 
order to facilitate a prompt reply. The thread can then call DevPostDeviceModes and 
DevOpenDC as appropriate. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action on it, other than to set u/Action to the default value of NULL. 


DM_RENDER 


This message is used to request a source to provide a rendering of an object in a specified 
rendering mechanism and format. 


Parameters 
param1 


pDxfer (PDRAGTRANSFER) 
Pointer to the DRAGTRANSFER structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion. 
FALSE — Error occurred. 


Remarks 

The target sends this message to a source window to request a rendering of an object. If 
the source returns FALSE, it may set flags in the DRAGTRANSFER structure that tell the 
target how to perform the rendering operation on its own, or how to retry the operation. If no 
flags are set, the source will not allow a rendering of the object. 


if TRUE is returned, the message was processed by the recipient and the requested 
rendering will take place. The source will post a DM_RENDERCOMPLETE message to the 
target when the rendering is complete. 


lf FALSE is returned, either the message was not processed by the recipient, or the recipient 
could not perform the requested rendering. See fsReply in DRAGTRANSFER for more 
information. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. 


DM_RENDERCOMPLETE 


This message is posted by a source to a target window. It informs the target that the source 
has completed a requested rendering operation. 


Parameters 
param1 


pDxfer (PDRAGTRANSFER) 
Pointer to the DRAGTRANSFER structure. 


param2 


usFS (USHORT) 
Flag field. 


Flag field indicating successful completion. 


DMFL_RENDERFAIL The source is unable to perform the rendering operation. 
The target may be allowed to retry. If the target is 
allowed to retry and chooses not to, it must send a 
DM_ENDCONVERSATION message to the source. 
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DMFL_RENDEROK The source has completed the rendering operation. 
When the target completes its part of the rendering 
operation, it must post a DM_RENDERCOMPLETE 
message to the source. 


DMFL_RENDERRETRY _ The source has completed the rendering operation and 
will allow the target to retry its part of the operation if it 
fails. This flag can be set in conjunction with either the 
DMFL_RENDERFAIL or DMFL_RENDEROK flags. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

If the rendering operation failed for any reason, the source can allow the target to retry the 
operation. The source should return to the state it was in when the drop occurred for that 
object. The target resumes the rendering operation from the beginning. 


If the rendering operation encounters a permanent failure, the source should fail the 
operation and proceed as if the rendering was completed. 


If the rendering operation completes successfully, the source should return to the state it was 
in when the drop occurred for that object. This allows the target to retry the operation if its 
portion of the rendering failed. The target must post a DM_ENDCONVERSATION message 
when either of the following occurs: 


e {t determines that the rendering operation successfully completed 
e It chooses not to retry a rendering operation that failed. 


Default Processing 

The WinDefWindowProc function should send a DM_ENDCONVERSATION message to the 
window indicated in the hwndltem field of the DRAGITEM structure. The message should 
indicate that the target failed in its part of the rendering operation. Sending the 
DM_ENDCONVERSATION message allows the source to release the resources it dedicated 
to the rendering operation. 
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DM_RENDERFILE 


This message is sent to the caller of DrgDragFiles to tell it to render a file. 


Parameters 
param1 


rndf (PRENDERFILE) 
Pointer to a RENDERFILE structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Render handling. 


TRUE _ The receiver handled the rendering. 
FALSE DrgDragFiles should render this file. 


Remarks 

This message is sent when TRUE is specified in DrgDragFiles. The receiver should perform 
the operation indicated by the TRUE field in the RENDERFILE structure, moving or copying 
hstrSource to hstrTarget. 


When the operation is complete, a DM_FILERENDERED message should be sent to 
hwndDragFiles window. 


The RENDERFILE structure is allocated temporarily for the receiver of this message. The 
receiver should make a copy if it needs to use the data in this structure after returning. 


Default Processing 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. 
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DM_RENDERPREPARE 


This message tells a source to prepare for the rendering of an object. 


Parameters 
_param1 


pDxfer (PDRAGTRANSFER) 
Pointer to a DRAGTRANSFER structure. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE The message was processed by the recipient and it is ready to perform the 
rendering operation. The target of the drop sends a DM_RENDER message 
to request the rendering with a specific rendering mechanism and format. 


FALSE The message either was not processed by the recipient, or it is unprepared to 
perform the rendering. The hwndlitem field in DRAGITEM may not be properly 
initialized, and therefore the target should not send a 
DM_ENDCONVERSATION message. 


Remarks 
This message must be sent when DC_PREPARE is on in the DRAGITEM structure. 


This message is used to allow the source to create an invisible window to handle the 
conversation required for the data transfer. 


Default Processing . 
The WinDefWindowProc function does not expect to receive this message and takes no 
action other than to return 0. 
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Chapter 29. Dynamic Data Exchange Messages 


Purpose 
This section describes the message part of the DDE protocol, which is a set of guidelines 
that allows two applications to share data freely between one another; not necessarily driven 
directly by user input. 


Note: DDE operates between two specific applications, each of which must be aware of the 
other, and active. 


WinDdelnitiate, WinDdePostMsg, and WinDdeRespond are the functions associated 
with these messages. 


WM_DDE_ACK 
This message notifies an application of the receipt and processing of a 
WM_DDE_EXECUTE, WM_DDE_ DATA, WM_DDE_ADVISE, WM_DDE_UNADVISE or 
WM_DDE_POKE message, and in some cases, of a WM_DDE_REQUEST message. 


This message is always posted. 


Parameters 
param1 


hwnd (HWND) 
Window handle of the sender. 


param2 


pDdeStruct (PDDESTRUCT) 
DDE structure. 


This points to a dynamic data exchange structure. See “DDESTRUCT’ on 
page A-46. 


The acknowledging application modifies the fsStatus field to return information about 
the status of the message received: 


DDE_FACK 1=request accepted, 0=request not accepted 
DDE_FBUSY | 1=busy, O=not busy 

DDE_NOTPROCESSED Reserved for application-specific return codes 
DDE_FAPPSTATUS The message was not understood and was ignored. 


An application is expected to set DDE_FBUSY if it is unable to respond to the 
request at the time it is received. The DDE_FBUSY flag is defined only when . 
DDE_FACK is 0. 


offszitemName identifies the item for which the acknowledgment is being sent. 
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Returns 
ulReserved (ULONG) 


Reserved value, should be 0. 


Default Processing 
None. 


WM_DDE_ADVISE 


This message (posted by a client application) requests the receiving application to supply an 


update for a data item whenever 


This message is always posted. 


Parameters 
param1 


hwnd (HWND) 


it changes. 


Window handle of the sender. 


param2 


pDdeStruct (PDDESTRUCT) 


DDE structure. 


This points to a dynamic data exchange structure. See “DDESTRUCT” on 


page A-46. 


Flags in the fsStatus field are set as follows: 


DDE_FACKREQ 


DDE_FNODATA 


If this bit is 1, the receiving (Server) application is requested 
to send its WM_DDE_DATA messages with the 
acknowledgment-requested (DDE_FACKREQ) bit set. This 
offers a flow control technique, whereby the client 
application can avoid overload from incoming 
WM_DDE_DATA messages. 


If this bit is 1, the server is requested to send its 
WM_DDE_DATA messages with a zero length data portion. 
These messages are alarms that tell the client the source 
data has changed. Upon receiving one of these alarms, the 
client can choose to call for the latest version of the data 
by issuing a WM_DDE_REQUEST message, or the client 
can choose to ignore the alarm. This is typically used when 
there is a significant resource cost associated with actually 
rendering and/or assimilating the data. 


offszitemName identifies which data item is being requested. 


29-2 PM Programming Reference Vol II 


usFormat is the preferred type of data of the client. It must be a registered DDE 
data format number. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The receiving application is expected to reply with a positive WM_DDE_ACK message if it 
can provide the requested data, or with a negative one if it can not. 


Default Processing 
None. 


WM_DDE_DATA 


This message notifies a client application of the availability of data. It is always posted. 


Parameters 
param1 


hwnd (HWND) 
Window handle of the sender. 


param2 


pDdeStruct (PDDESTRUCT) 
DDE structure. 


This points to a dynamic data exchange structure. See “DDESTRUCT” on 

page A-46. 

Flags in the fsSiatus field are set as follows: 

DDE_FACKREQ If this bit is 1, the receiving (client) application is expected 
to send a WM_DDE_ACK message after the memory 


object has been processed. If it is 0, the client application 
should not send a WM_DDE_ACK message. 


DDE_FRESPONSE If this bit is 1, this data is offered in response to a 
WM_DDE_REQUEST message. If it is 0, this data is 
offered in response to a WM_DDE_ADVISE message. 


offszitemName identifies which data item is available. 


offabData is the data. The format of the data is a registered DDE data format, 
identified by the usFormat field. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
None. — 


WM_DDE_EXECUTE 
This message posts a string to a server application to be processed as a series of 
commands. The server application is expected to post a WM_DDE_ACK message in 
response. 


This message is always posted. 


Parameters 
param1 


hwnd (HWND) 
Window handle of the server. 


param2 


pDdeStruct (PDDESTRUCT) 
DDE structure. 


This points to a dynamic data exchange structure. See “DDESTRUCT” on 
page A-46. 


offabData contains the commands to be executed. 
Returns 


ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
None. 


WM_DDE_INITIATE 


“This message is sent by an application to one or more other applications, to raguisst initiator 
of a conversation. 


This message is always sent. 
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Parameters 
param1 


hwnd (HWND) 
Window handle of the sender. 


param2 


pData (PDDEINIT) 
Pointer to initiation data. 


This points to a DDEINIT structure. pszAppName is the name of the desired server 
application; if this is a zero-length string, any application can respond. pszTopic is 
the name of the desired topic; if this is a zero-length string, each responding 
application responds once for each topic that it can support. 


Returns 
re (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE _ Error occurred. 


Remarks 

Upon receiving this message, all applications with names matching the application name 
(where specified), that support the topic identified by the topic name, are expected to 
acknowledge. 


A modal window, for example a message box, must not be invoked during the processing of 
this message. 


Default Processing 
The default window procedure frees the segment referenced by param2. 
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WM_DDE_INITIATEACK 


This message is sent by a server application in response to a WM_DDE_INITIATE message, 
for each topic that the server application wishes to support. . 


Parameters 
param 


hwnd (HWND) 
Window handle of the sender. 


| param2 


pData (PDDEINIT) 
Pointer to initiation data. 


This points to a DDEINIT structure. pszAppName is the name of the responding 
server application; it must not be a zero-length string. pszTopic is the name of the 
topic that the server is willing to support; it must not be a zero-length string. 


The DDEINIT structure must be in a shareable segment; it is the responsibility of 
the receiving window procedure to free this segment. 


Returns 
rc (BOOL) 
Success indicator. 


TRUE Successful completion 
FALSE Error occurred. 


Remarks 
A modal window, such as a message box, must not be posted during the processing of this 
message. 


Default Processing : 
The default window procedure frees the segment referenced by param2. 


WM_DDE_POKE 


This message requests an application to accept an unsolicited data item. It is always 
posted. 


Parameters 
paramt1 


hwnd (HWND) 
Window handle of the sender. 
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param2 


pDdeStruct (PDDESTRUCT) 
DDE siructure. 


This points to a dynamic data exchange structure. See “DDESTRUCT” on 
page A-46. 


offszitemName identifies the data item to the receiving application. 


offabData is the data. The format of the data is a registered DDE data format, 
identified by the usFormat field. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The receiving application is expected to reply with a positive WM DDE ACK message if it 
accepts the unsolicited data, or with a negative WM_DDE_ACK if it does not. 


Default Processing 
None. 


WM_DDE_REQUEST 


This message is posted from client to server, to request that the server provide a data item 
to the client. 


This message is always posted. 


Parameters 
param1 


hwnd (HWND) 
Window handle of the server. 


param2 


DdeStruct (PDDESTRUCT) 
DDE siructure. 


This points to a dynamic data exchange structure. See “DDESTRUCT” on 
page A-46. 


offszitemName identifies which data item is being requested. 
usFormat identifies in which registered DDE data format the data item is to be 
rendered. 
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Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The receiving application is expected to respond with a WM_DDE_ DATA message, 
containing the requested data, if possible. Otherwise, it is expected to respond with a 

negative WM_DDE_ACK message. 


Default Processing 
None. 


WM_DDE_TERMINATE 


“This message is posted by either Bppiecton participating in a DDE conversation, to 
terminate that conversation. 


This message is always posted. 


Parameters 
param1 


hwnd (HWND) 
Window handle of the sender. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
Upon receiving this message, an application is expected to post a WM_DDE_TERMINATE 
message in response. 


Default Processing 
None. 
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WM_DDE_UNADVISE 


This message is posted by a client application to a server application to indicate that the 
specified item should no longer be updated. 


This message is always posted. 


Parameters 
param1 


hwnd (HWND) 
Window handle of a sender. 


param2 


DdeStruct (PDDESTRUCT) 
DDE structure. 


This points to a dynamic data exchange structure (see “DDESTRUCT” on 
page A-46). offszitemName identifies which data update request is to be retracted. 
If this is a zero-length string, data update requests for all items are retracted. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The receiving application is expected to reply with a positive WM_DDE_ACK message if it 
can honor the request, or a negative one if it cannot. 


Default Processing 
None. 
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Chapter 30.. Help Manager Messages 


Purpose 
This section describes the processing of messages sent by the Help Manager or applications 
in response to requests for help by the user. 


HM_ACTIONBAR_COMMAND 


This message is sent to the current active application window by the Help Manager to notify 
the application when the user selects a tailored action bar item. 


Parameters 
param1 


idCommand (USHORT) 
Identity of the action bar item that was selected. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Default Processing 
None. 


HM_CONTROL 


This message is sent by the Help Manager to the child of the coverpage window to add a 
control in the control area of a window. 


Parameters 
param1 


usReserve (USHORT) 
Reserved value. 
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controlres (USHORT) 
Res number of the control that was selected. 


For author-defined push buttons, this is the res identification number that was 
specified with the push button tag (:pbutton.). For default push buttons, this is the 
res identification number defined in the PMHELP.H file. 


param2 


ulReserved (ULONG) 
Reserved value. 


Returns 
ulReserved (ULONG) . 
Reserved value, should be 0. 


Remarks 

If an application wants to filter any of the controls, it can subclass the child of the coverpage 
window and intercept this message. If the application does not intercept this message, the 
Help Manager adds the control to the control area. 


Default Processing 
None. 


HM_CREATE_HELP_TABLE 


This message is sent by the application to give the Help Manager a new help table. 


Parameters 
param1 


pHELPTABLE (PHELPTABLE) 
Help table. 


This points to a help table structure; see “HELPTABLE” on page A-108. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (ULONG) 
Return code. 


0 The procedure was successfully completed 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Default Processing 
None. 


HM_DISMISS_WINDOW 


This message tells the Help Manager to remove the active help window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
~ Return code. 


0 The help window was successfully removed 
Other There was no associated help window. 


See also the values of the u/ErrorCode parameter of the HM_ERROR message. 


Remarks 

If the user requests help from a primary or secondary window, and then interacts with the 
primary or secondary window without leaving help, the currently displayed help window might 
not be appropriate for the application window. This message gives the application the ability 
to remove that help window. 


Default Processing 
None. 
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HM_DISPLAY_HELP 


This message tells the Help Manager to display a specific help window. 


Parameters 
param1 


idHelpPanelld (USHORT) 
Identity of the help window. 


This points to a USHORT data type. 
For a value of the usTypeFlag parameter of HU_PANELNAME. 


pszHelpPanelName (PSZ) 
Name of the help window. 


This points to a string containing the name of the help window. 


param2 


usTypeFlag (USHORT) 
Flag indicating how to interpret the first parameter. 


w 


HM_RESOURCEID Indicates the param points to the identity of the help 
window. 


HM_PANELNAME Indicates the param? points to the name of the help window. 


Returns 
re (ULONG) 
Return code. 


0 The window was successfully displayed 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Remarks 
param?! depends on the value of the usTypeFlag parameter. 


Default Processing 
None. 
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HM_ERROR 


This message notifies the application of an error caused by a user interaction. 


Parameters 
param1 


ulErrorCode (ULONG) 
Error code. 


A constant describing the type of error that occurred. The application can also 
receive some of these error constants in the u/Reserved parameter of messages it 
has sent to the Help Manager. 


The error constants are: 


HMERR_LOAD_DLL 
The resource DLL was unable to be loaded. 
HMERR_NO_FRAME_WND_IN_CHAIN 
There is no frame window in the window chain from which to find or set the 
associated help instance. 


HMERR_INVALID_-ASSOC_APP_WND 
The application window handle specified on the WinAssociateHelpInstance 
function is not a valid window handle. 
HMERR_INVALID_ASSOC_HELP_INST 
The help instance handle specified on the WinAssociateHelpInstance function 
is not a valid window handle. 


HMERR_INVALID_DESTROY_HELP_INST 
The window handle specified as the help instance to destroy is not of the help 
instance class. 


HMERR_NO_HELP_INST_IN_CHAIN 
The parent or owner chain of the application window specified does not have 
an associated help instance. 


HMERR_INVALID_HELP_INSTANCE_HDL 
The handle specified to be a help instance does not have the class name of a 
Help Manager instance. 


HMERR_INVALID_ QUERY_APP_WND 
The application window specified on a WinQueryHelpinstance function is not a 
valid window handle. 


HMERR_HELP_INST_CALLED_INVALID . 
The handle of the instance specified on a call to the Help Manager does not 
have the class name of a Help Manager instance. . 


HMERR_HELPTABLE_UNDEFINE 
The application did not provide a help table for context-sensitive help. 
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HMERR_HELP_INSTANCE_UNDEFINE 
The help instance handle specified is invalid. 


HMERR_HELPITEM_NOT_FOUND 
Context-sensitive help was requested but the ID of the main help item specified 
was not found in the help table. 


HMERR_INVALID_HELPSUBITEM_SIZE 
The help subtable item size is less than 2. 


HMERR_HELPSUBITEM_NOT_FOUND 
Context-sensitive help was requested but the ID of the help item specified was 
not found in the help subtable. 


HMERR_INDEX_NOT_FOUND 
The index is not in the library file. 


HMERR_CONTENT_NOT_FOUND 

The library file does not have any content. 
HMERR_OPEN LIB FILE 

The library file cannot be opened. 
HMERR_READ LIB FILE 

The library file cannot be read. 
HMERR_CLOSE_LIB_FILE 

The library file cannot be closed. 
HMERR_INVALID_LIB_ FILE 

Improper library file provided. 
HMERR_NO_MEMORY 

Unable to allocate the requested amount of memory. 


THMERR_ALLOCATE_SEGMENT 
Unable to allocate a segment of memory for memory allocation requests from 
the Help Manager. 


HMERR_FREE_MEMORY 
Unable to free allocated memory. 


HMERR_PANEL_NOT_FOUND 
Unable to find the requested help window. 


HMERR_DATABASE_NOT_OPEN 
Unable to read the unopened database. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. | 
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Returns 
ulReserved (ULONG) 
- Reserved value, should be 0. 


Remarks 

There is no other way to communicate the error to the application since the user initiated 
communication, not the application. Other errors which occur when the application sends a 
message to the Help Manager are returned as the u/Reserved parameter of the message. 


The Help Manager does not display any error messages to the user. Instead, the Help 
Manager sends or returns all error notifications to the application so that it can display its 
own messages. This procedure ensures a consistent message interface for all user 
messages. 


Default Processing 
None. 


HM_EXT_HELP 


When the Help Manager receives this message, it displays the extended help window for the 
active application panel. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The extended help window was successfully displayed 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Default Processing 
None. 
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HM_EXT_HELP_UNDEFINED 


This message is 5 sent to the application by the Help Manager: to notify it that an extended 
help window has not been defined. 


Pursineleks 
param! 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
When the extended help window is requested, the Help Manager searches the help table for 
its identity. If the extended help window identity associated with the current active window is 
zero, the Help Manager sends this message to the application to notify it that an extended 
help window has not been defined. The application then can: 

e Ignore the request for help and not display a help window. 

e Display its own window. 


e Use the HM_DISPLAY_HELP message to tell the Help Manager to display a particular 
window. 


Default Processing 
None. 


HM_GENERAL_HELP 


When the Help Manager receives this message, it displays the general help window for the 
active application window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The general help window was successfully displayed. 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Default Processing 
None. 


HM_GENERAL_HELP_UNDEFINED 


This message is sent to the application by the Help Manager to notify it that a general help 
window has not been defined. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved. 


O Reserved value, 0. 


Returns 
ulReserved (\JLONG) 
Reserved vaiue, should be 0. 


Remarks 

When the general help window is requested, the Help Manager searches the help table for 

its identity. If the general help window identity associated with the current active window is 

zero, the Help Manager sends this message to the application to notify it that a general help 
~ window has not been defined. The application can then: 


e Ignore the request for help and not display a help window. 


e Display its own window. 
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e Use the HM_DISPLAY_HELP message to tell the Help Manager to display a particular 
window. . 


Default Processing 
None. 


HM_HELP_CONTENTS 


When the Help Manager receives this message, it displays the help contents window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The help contents window was successfully displayed. 
Other See the values of the u/ErrorCode parameter of the HU_ERROR message. 


| Default Processing 
None. 


HM_HELP_INDEX 


When the Help Manager receives this message, it displays the help index window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
re (ULONG) 
Return code. 


0 The help index window was successfully displayed. 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Default Processing 
None. 


HM_HELPSUBITEM_NOT_FOUND 


The Help Manager sends this message to the application when the user requests help on a 
field and it cannot find a related entry in the help subtable. 


Parameters 
param1 


usContext (USHORT) 
Type of window on which help was requested. 


HLPM_WINDOW An application window 
HLPM_FRAME A frame window 
HLPM_MENU A menu window. 


param2 


sTopic (SHORT) 
Topic identifier. 


For a value of the usContext parameter of HLPM_WINDOW or HLPM_FRAME: 


window _ Identity of the window containing the field on which help was requested. 
menu Identity of the submenu containing the field on which help was requested. 


sSubTopic (SHORT) 
Subtopic identifier. 


For a value of the usContext parameter of HLPM_WINDOW or HLPM_FRAME: 
control Control identity of the cursored field and on which help was requested. 
For a value of the usContext parameter of HLPM_MENU: 


~1 No menu item was selected 


other Menu item identity of the currently selected submenu item on which 
help was requested. 
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Returns 
rc (BOOL) 
Action indicator. 


Remarks 
If FALSE is returned from this message, the Help Manager displays the extended help 
window. 
The application has the following options: 
e Ignore the notification and not display help for that field or window. 
¢ Display its own window. : | 


e Use the HM _DISPLAY_HELP message to tell the Help Manager to display a particular 
window. 


Default Processing 
None. 


HM_INFORM 
' This message is used by the Help Manager to notify the application when the user selects a 
hypertext field that was specified with the reftype=inform attribute of the :link. tag. 


Parameters 
param1 


idnum (USHORT) 
Window identity. 


The identity that is associated with the hypertext field. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


QO Reserved value, zero. 


Default Processing 
None. 
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HM_INVALIDATE_DDF_DATA 


The application sends this message to IPF to indicate that the previous DDF data is no 
longer valid. 


Parameters 
param1 


rescount (ULONG) 
The count of DDFs to be invalidated. 


param2 


resarray (PUSHORT) 
Pointer to an array. 


The pointer to an array of unsigned 16-bit (USHORT) integers that are the res 
numbers of DDFs to be invalidated. 


Note: If both param1 and param2 are NULL, then all the DDFs in that page will be 
invalidated. 


Returns 
rc (ULONG) 
Return code. 


0 The procedure was successfully completed. 
Other See the values of the errorcode parameter of the HMU_ERROR message. 


Remarks 
When IPF receives this message, it discards the current DDF data and sends a new 
HM_QUERY_DDF_DATA message to the object communication window. 


This message shouid be sent to the child of the coverpage window handle. 


Default Processing 
None. 
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HM_KEYS_ HELP 
This message is sent by the application and informs the help manager to display the keys 
help window. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The keys help window was successfully displayed 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Remarks 

When the Help Manager receives this message, it sends a HM_QUERY_KEYS_HELP 
message to the active application window. The active application window is the window that 
was specified when the last HMU_SET_ACTIVE_WINDOW message was sent. If no 
HM_SET_ACTIVE_WINDOW message was issued, then the active application window is the 
window specified in the WinAssociateHelpInstance call. 


The application must return one of the following: 


¢ The identity of a keys help window in the usHelpPanel parameter of the 
HM_QUERY_KEYS_HELP message. 


e Zero, if no action is to be taken by the Help Manager for keys help. © 


Default Processing 
None. 
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HM_LOAD HELP TABLE 


The application sends this message to give the Help Manager the module handle that 
contains the help table, the help subtable, and the identity of the help table. 


Parameters 
param1 


idHelpTable (USHORT) 
Identity of the help table. 


fsidentityflag (USHORT) 
Help table identity indicator. 


OxFFFF Reserved value. 


param2 


MODULE (HMODULE) 
Resource identity. 


Handle of the module that contains the help tabie and help subtable. 


Returns 
re (ULONG) 
Return code. 


0 The procedure was successfully completed. 
Other See the values of the ulErrorCode parameter of the HMV_ERROR message. 


Default Processing 
None. 


HM_NOTIFY 


This message is used by the application to sub-class and change the behavior or 
appearance of the help window. 


Parameters 
param1 


controlres (USHORT) 
Res number of the control that was selected. 


For author-defined push buttons, this is the res number that was specified with the 
push button tag (:pbutton.). For default push buttons, this is the res number 
defined in the PMHELP.H file. 
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usReserve (USHORT) 
Reserved value, should be 0. 


Reserved for events other than CONTROL_SELECTED and HELP_REQUESTED. 


usevent (USHORT) 
‘The type of event which has occurred. 


CONTROL_SELECTED A control was selected. 

HELP_REQUESTED Help was requested. 

OPEN_COVERPAGE The coverpage is displayed. 

OPEN_PAGE The child window of the coverpage is opened. 
SWAP_PAGE The child window of the coverpage is swapped. 
OPEN_INDEX The index window is displayed. 

OPEN_TOC The table of contents window is displayed. 
OPEN_HISTORY The history window is displayed. 
OPEN_LIBRARY The new library is opened. 


OPEN SEARCH HITLIST The search list displayed. 


param2 


ulhwnd (ULONG) 
Window handle of relevant window. 


Returns 
re (BOOL) 
Return code. 


TRUE IPF will not format the controls and re-size the window. 
FALSE IPF will process as normal. 


' Remarks 
This message is sent to the application to notify it of events that the application would be 
interested in controlling. 


Default Processing 
None. 
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HM_QUERY 


This message is sent to IPF by the application to request IPF-specific information, such as 
the current Instance handle, the active communication object window, the active window, or 
the group number of the current window. 


Parameters 
param1 


usselectionid (USHORT) 
What is being requested. 


This parameter should be specified only if the query is for HAQW_VIEWPORT and 
should otherwise be coded as NULL. 


Specifies whether a res ID, ID number, or group number is being requested. The 
value can be any of the following constants: 


HMQVP_NUMBER 
HMQVP_NAME 
HMQVP_GROUP 


usmessageid (USHORT) 
Type of window queried. 


A pointer to a USHORT that holds the res ID of the 
window. 


A pointer to a null-terminated string that holds the ID 
of the window. 


The group number of the window. 


Specifies the type of window to query. The value can be any of the following 


constants: 

HMQW_INDEX 
HMQW_TOC 
HMQW_SEARCH 
HMQW_VIEWEDPAGES 
HMQW_LIBRARY 
HMQW_OBJCOM_WINDOW 


HMQW_INSTANCE 
HMQW_COVERPAGE 


HMQW_VIEWPORT 


The handle of the index window. 

The handle of the Table of Contents window. 
The handle of the Search Hitlist window. 
The handle of the Viewed Pages window. 
The handle of the Library List window. 


The handle of the active communication 
window. 


The handle of the help instance. 


The handle of the help manager multiple 
document interface (MDI) parent window. It is 
where the secondary windows are contained 
within the parent window. 


The handle of the viewport window specified in 
the low-order word of param1 and in param2. 


When HMQW_VIEWPORT is specified in 
usmessageid, a value must be specified in 
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usselectionid to indicate whether a res ID, ID 
number, or group number is being requested. 


HMQW_GROUP_VIEWPORT The group number of the window whose 


handle is specified in param2. 
HMQW_RES_VIEWPORT The res number of the window whose handle 

is specified in param2. 
HMQW_ACTIVEVIEWPORT The handle of the currently active window. 
USERDATA The previously stored user-data. 


param2 


pvoid (PVOID) 
Varies, depending on value selected above. 


param2 depends on the value of param? usmessageid. 


If param? usmessageid is HMQW_VIEWPORT, then rete is a pointer to the res 
number, ID, or group ID. 


lf param? usmessageid is HMQW_GROUP_VIEWPORT, then param2 is the handle 
of the viewport for which the group number is assigned. 


If param? usmessageid is HMQW_RES_VIEWPORT, then param2 is the handle of 
the viewport for which the res number is requested. . 


Returns 
re (ULONG) 
Return code. 


0 The procedure was not successfully completed. 


Other The handle (HWND), group number (USHORT), or res number (USHORT) of 
the window, or the user data (USHORT), depending on the value of param? 
usselectionid. 


Default Processing 
None. 
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HM_QUERY_DDF_DATA 


This message is sent to the communication object window by IPF when it encounters the 
dynamic data formatting (:ddf.) tag. 


Parameters 
param1 


pageclienthwnd (HWND) 
Client handle. 


The client handle of the page that contains the object communication window. 


param2 


resid (ULONG) 
The res ID associated with the DDF tag. 


Returns 
re (HDDF) 
Return code. 


0 An error has occurred in the application’s DDF processing. 
Other The DDF handle to be displayed. 


Note: Once this handle has been returned, the HDDF handle can no longer be 
used by the application. 


Remarks 

Upon receiving this message, the communication object calls Ddflnitialize to indicate the start 
of dynamic data formatting (DDF). Any combination of other DDF calls are then made to 
describe this data. When this is complete, the communication object finishes processing this 
message, indicating that the DDF data is complete. After that time, the DDF handle received 
from Ddflnitialize is considered invalid. 


Default Processing 
None. 


Chapter 30. Help Manager Messages 30-19 


HM_QUERY_KEYS_HELP 


When the user requests the keys help function, the Help Manager sends this message to the 
application. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
usHelpPanel (USHORT) 
Help panel ID. 


The identity of the application-defined keys help window to be displayed. 


0 Do nothing 
Other Identity of the keys help window to be displayed. 


Remarks 

The application responds by returning the identity of the requested keys help window. The 
‘Help Manager then displays that help window. Returning O in the usHelpPane/ parameter 
indicates that the Help Manager should do nothing for the keys help function. 


Default Processing 
None. 


HM_REPLACE_HELP_FOR_HELP 


This message tells the Help Manager to display the application-defined Help for Help window 
instead of the Help Manager Help for Help window. 


Parameters 
paramt 


idHelpForHelpPanel (USHORT) 
Identity of the application-defined Help for Help window. 


0 Use the Help Manager Help for Help window. 
Other Identity of the application-defined Help for Help window. 
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param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
An application may prefer to provide information that is more specific to itself, rather than the 
more general help information provided in the Help Manager Help for Help window. 


Default Processing 
None. 


HM_REPLACE_USING_HELP 


This message tells the Help Manager to display the application-defined Using help window 
instead of the Help Manager Using help window. 


Parameters 
param 


idUsingHelpPanel (USHORT) 
The identity of the application-defined Using Help window. 


0 Use the Help Manager Using Help window. 
Other The identity of the application-defined Using Help window. 


| param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

An application may prefer to provide information that is more specific to itself, rather than the 
more general help information that is provided in the Help Manager Using help window. The 
guidelines that define the current CUA interface recommend the Using help choice be 
provided in a pull-down menu from the Help choice. 
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Default Processing 
None. 


HM_SET_ACTIVE_WINDOW 


This message allows the application to change the window with which the Help Manager 
communicates and the window to which the help window is to be positioned. 


Parameters 
param1 


hwndActiveWindow (HWND) 
The handle of the window to be made active. 


lts window procedure receives all messages from the Help Manager until the 
application changes the active window with another HM_SET_ACTIVE_WINDOW 
message. 


param2 


hwndRelativeWindow (HWND) 
The handle of the window next to which the help window is to be positioned. 


The handle of the application window next to which the Help Manager will position a_ 
new help window. 


HWND_PARENT _ This Help Manager defined constant tells the Help Manager to 
trace the parent chain of the window that had the focus when 
the user requested help. 


Other Handle of the window next to which the help window is to be 
: positioned. 
Returns 
~ re (ULONG) 


Return code. 


0 The procedure has been successfully completed. 
Other See the values of the ulErrorCode parameter of the HM_ERROR message. 


Remarks . 
Normally the Help Manager communicates with the application window with which the Help 
Manager instance has been associated. The help window is positioned next to this same 
application window. 


If the hwndActiveWindow parameter is 0, the hwndRelativeWindow parameter is set to 0. 
That is, if the active window is NULL HANDLE, the relative window is not used. 
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Default Processing 
None. 


HM_SET_COVERPAGE SIZE 


This message is sent to IPF by the application to set the size of the coverpage, the window 
within which all other IPF windows are displayed. 


Parameters 
param1 


coverpagerectl (PRECTL) 
Pointer to RECTL containing the size of the coverpage. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The procedure was successfully completed. 
Other See the values of the errorcode parameter of the HM_ERROR message. 


Remarks 
The default size for the coverpage of a book is the full width of the screen, while the default 
size for a help file is one-half the width of the screen. 


This message takes effect immediately, changing the size of the coverpage. If the 
coverpage is not currently open, the requested size is saved for the next open. 


Default Processing 
None. 
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HM_SET_HELP_LIBRARY_NAME 


This message identifies a list of help window library names to the Help Manager instance. 


Parameters 
param1 


pszHelpLibraryName (PSZ) 
Library name. 


This points to a string that contains a list of help window library names that will be 
searched by the Help Manager for the requested help window. The names must be 
separated by a blank. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The newly specified library successfully replaced the current help window library 
name. 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Remarks 
Any subsequent communication to the Help Manager with this message replaces the current 
list of names with the newly specified list. 


When help is requested, the Help Manager will search each library in the list for the 
requested help window. | 


Default Processing 
None. 
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HM_SET HELP WINDOW TITLE 


This message allows the application to change the window text of a help window title. 


Parameters 
param1 


pszHelpWindowTitle (PSZ) 
Help window title. 


This points to a string containing the new Help Window title. 


param2 — 


ulReserved (ULONG) 
Reserved value, should be 0. 


Returns 
re (ULONG) 
Return code. 


0 The window title was successfully set. 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Default Processing 
None. 


HM_SET_OBJCOM_WINDOW 
This message is sent to IPF by the application to identify the communication object window 
to which the HM_INFORM and HM_QUERY_DDF_DATA messages will be sent. This 
message is not necessary if the communication object does not expect to receive either of 
these messages. 


Parameters 
hwndparam1 


objcomhwnd (HWND) 
Handle of the communication object window to be set. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 
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Returns 
hwndprevioushwnd (HWND) 
The handle of the previous communication object window. 


Remarks. 

HM_INFORM and HM_QUERY_DDF_DATA messages which are not processed must be 
passed to the previous communication object window which was returned when 
HM_SET_OBJECT_WINDOW was sent. 


Default Processing 
None. 


HM_SET_SHOW_PANEL ID 


This message tells the Help Manager to display, hide, or toggle the window identity for each 
help window displayed. 


Parameters 
param1 


fsShowPanelld (USHORT) 
The show window identity indicator. 


CMIC_HIDE_PANEL_ID Sets the show option off and the window identity is 
not displayed. 

CMIC_SHOW_PANEL_ID Sets the show option on and the window identity is 
displayed. 


CMIC_TOGGLE_PANEL_ID Toggles the display of the window identity. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


re (ULONG) 
Return code. 


0 The show window identity indicator was successfully changed. 
Other See the values of the u/ErrorCode parameter of the HM_ERROR message. 


Default Processing 
None. 
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HM_SET_USERDATA 


The application sends this message to IPF to store data in the IPF data area. 


Parameters 
param1 


ulReserved (ULONG) 
Reserved value, should be 0. 


param2 


usrdata (VOID) 
4-byte user data area. 


re (ULONG) 
Return code. 


TRUE _ The user data was successfully stored. 
FALSE _ The call failed. 


Default Processing 
None. 


HM_TUTORIAL 


The Help Manager sends this message to the application window when the user selects the 
Tutorial choice from a help window. 


Parameters 
param1 


pszTutorialName (PSZ) 
Default tutorial name. 


This points to a string that contains the name of the default tutorial program 
specified in the Help Manager initialization structure. A tutorial name specified in 
the help window definition overrides this default tutorial program. 


param2 


ulReserved (ULONG) 
Reserved value, should be 0. 


Chapter 30. Help Manager Messages 30-27 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 
The application then calls its own tutorial program. 


Default Processing 
None. 


HM_UPDATE_OBJCOM_WINDOW_CHAIN > 


This message is sent to the currently active communication object by the communication 
object who wants to withdraw from the communication chain. 


Parameters 
param1 . 


hwnd (HWND) 
The handle of the object to be withdrawn from the communication chain. 


param2 


hwnd (HWND) 
Window containing the handle of the object to be replaced. 


Returns 
ulReserved (ULONG) 
Reserved value, should be 0. 


Remarks 

The object that receives this message should check to see if the object handle returned from 
HM_SET_OBJCOM_WINDOW is equal to the handle in param?. \f the handle is equal, then 
the handle in param1 should be replaced by the handle in param2. If the handle is not equal 
and the handle previously received is not NULL HANDLE, then send 
HM_UPDATE_OBJCOM_WINDOW_CHAIN to that object. 


Default Processing 
None. 
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Chapter 31. Resource Files 


This chapter describes the syntax for the resource language using railroad syntax, and 
describes the formats used. 


Resource files are used to build dialog templates, menu templates, accelerator tables, 
extended attribute association tables, keyboard scancode mapping tables, keyboard names 
and fonts. The files must be compiled before they can be used by application programs. 


How to Read the Syntax Definitions 


Throughout this book, syntax is described using the structure defined below. 


Read the syntax diagrams from left to right, from top to bottom, following the path of the 
line. 


The »»>—— symbol indicates the beginning of a statement. 

The ——» symbol indicates that the statement syntax is continued on the next line. 
The »—— symbol indicates that a statement is continued from the previous line. 
The -—»< symbol indicates the end of a statement. 


Diagrams of syntactical units other than complete statements start with the »—— symbol 
and end with the —-> symbol. 


Required items appear on the horizontal line (the main path). 
>>—STATEMENT 


required_item—_—-_>< 


Optional items appear below the main path. 


i eee = 
optional ite 


If a choice can be made from two or more items, they appear vertically, in a stack. 


If one of the items must be chosen, one item of the stack appears on the main path. 
pe EME ioe red_choi ae re 
required_choice2 


If choosing one of the items is optional, the entire stack appears below the main path. 


>>——STATEMENT 
[optional _choicel— 
optional_choice2 


An arrow returning to the left above the main path indicates an item that can be 


repeated. 
repeatable_ite 


A repeat arrow above a stack indicates that a choice can be made from the stacked 
items, or a single choice can be repeated. 


>>—— STATEMENT 
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¢ Keywords appear in uppercase, (for example, PARM1). They must be spelled exactly as 
shown. Variables appear in all lowercase letters (for example: parmx). They represent 
user-supplied names or values. 


¢ If punctuation marks, parentheses, arithmetic operators, or such symbols are shown, 
they must be entered as part of the syntax. 


Definitions Used in all Resources 


The definitions used in all resources are defined in Specification of Values and Resource 
Load and Memory Options. 


Specification of Values 
These rules apply to values specified in resources: 


¢ Coordinates must be integers. There must be no space between the sign of the value 
and the value itself. For example, “—1” is allowed but “- 1” is not. 


_e Resource identifiers must be positive integers or names that resolve to positive integers. 


e Real values, containing a decimal point, cannot be used. 


Resource Load and Memory Options 
The following options define when each resource is loaded and how memory is allocated for 
each resource. 


LOADOPTION _ Resource loading options. 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 


MEMOPTION Resource memory options. 


FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary to 
compact. 

DISCARDABLE Resource can be discarded if no longer needed. 

SEGALIGN Resources are aligned on 64K byte boundaries. 


Resource Script File Specification 


The resource script file defines the names and attributes of the resources to be added to the 
executable file of the application. The file consists of one or more resource statements that 
define the resource type and original file, if any. See the following for a description of the 
resource statements: 


e Single-Line Statements 

e User-Defined Resources 

e Directives 
¢ Multiple-Line Statements. 
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Single-Line Statements 
The general form for all single-line statements is: 


Single-line statement 


By = OUNCE DE MaMa ee 

loadoption 

Pe ]ename—>< 
emoption 


resourcetype (USHORT) 
One of the following keywords, specifying the type of resource to be loaded: 


Keyword Resource type 


BITMAP A bit-map resource is a custom bit map that an application intends to 
use in its screen display or as an item in a menu. 


DEFAULTICON This keyword installs the filename.ico icon definition under the ICON 
EA of the program file. 


Example: 


DEFAULTICON <filename.ico> 


DLGINCLUDE This statement teils the dialog editor which file to use as an include 
file for the dialogs in the resource file. The nameid is not applicable. 


FONT A font resource is a file containing a font. 


ICON An icon resource is a bit map defining the shape of the icon to be 
used for a given application. 


POINTER A pointer resource is a bit map defining the shape of the pointing 
device pointer on the display screen. 


nameid (USHORT) 
is either a unique name or an integer number identifying the resource. For a FONT 
resource, the nameid must be a number; it cannot be a name. 


loadoption (LOADOPTION) 
The default is LOADONCALL. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION.. 


memoption (MEMOPTION) 
The default is MOVEABLE and DISCARDABLE for POINTER, ICON, and FONT 
resources. The default for BITMAP resources is MOVEABLE. The FIXED option 
overrides both MOVEABLE and DISCARDABLE. The SEGALIGN option can be 
specified independently of other options, if it is not present the default (for all resources) 
is that the resource is not aligned on a 64KB boundary. 
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See “Resource Load and Memory Options” on page 31-2 for a description of 
MEMOPTION. 


filename (PCH) 
An ASCII string specifying the OS/2* name of the file containing the resource. A full 
path must be given if the file is not in the current working directory. 


Example 


POINTER pointer point.cur 
POINTER pointer DISCARDABLE point.cur 
POINTER 10 custom.cur 


ICON desk desk.ico 
ICON desk DISCARDABLE desk.ico 
ICON 11 custom.ico 


BITMAP disk disk.bmp 
BITMAP disk DISCARDABLE disk.bmp 
BITMAP 12 custom.bmp 


FONT 5 CMROMAN. FNT 


User-Defined Resources 
An application can also define its own resource. The resource can be any data that the 
_ application intends to use. A user-defined resource statement has the form: 


User-defined resource 
>>—resource-type—typeID—name I D-_________L#* 


Ua es | Seer Were 
loadoption emoption 


typelD 
Either a unique name or an integer number identifying the resource type., If a number is 
given, it must be greater than 255. The type numbers 1 through 255 are reserved for 
existing and future predefined resource types. Value 1000 is reserved for custom fonts. 


nameiD . 
Either a unique name or an integer number identifying the resource. 


loadoption (LOADOPTION) 
The default is LOADONCALL. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION. 


memoption (MEMOPTION) 
The default is MOVEABLE. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
MEMOPTION. 
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filename 
An ASCII string specifying the OS/2* name of the file containing the cursor bit map. A 
full path must be given if the file is not in the current working directory. 


When the resource compiler (RC.EXE) encounters one or more font resources, or any 
custom resource having type-id of 1000, it creates a font directory resource which it adds to 
the output binary data. 


Example 

RESOURCE MYRES array  DATA.RES 
RESOURCE 300 14 CUSTOM. RES 
RCDATA statement 


The RCDATA statement is provided to allow an application to define a simple data resource. 


RCDATA statement 
p>—RCDATA——i dl oadopt ion———-memopt i on—> 


newl j ne | 
iH_—_—_——data END--———->« 


id Either a unique name or an integer number identifying the resource. 


loadoption (LOADOPTION) 
The default is LOADONCALL. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION. 


memoption (MEMOPTION) 
The default is MOVEABLE. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
MEMOPTION. 


data 
A number or string. 
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Example: 


RCDATA 4 

BEGIN 
“Sample string." 
"TEST DATA." 
"A message." 

END 


Directives | 
The resource directives are special statements that define actions to perform.on the file 
before it is compiled. The directives can assign values to names, include the contents of 
files, and control compilation of the file. 


#include filename 


rcinclude filename 


These directives copy the contents of the file specified by filename into the resource 
before it is compiled. If rcinclude is used, the entire file is copied. If #include is used, 
only #define statements are copied. 


Note: If an rcinclude is to be commented out, the open comment (/*) must appear on 
the same line as the directive. 


Filename is an ASCII string. A full path must be given if the file is not in the current 
directory or in the directory specified by the INCLUDE environment variable. The file 
extensions .| and .TMP must not be used as these are reserved for system use. 


The filename parameter is handled as a C string, and two back-siashes must be given 
wherever one is expected in the path name (for example, root\\sub.) or, a single forward 
slash (/) can be used instead of double back-slashes (for example, root/sub.) 


Example: 


#include "wincalls.h" 


MENU PenSelect 
BEGIN 

MENUITEM "biack pen", BLACK_PEN 
END 


Files included in resource script files constants that use #define statements may not 
include any casting of those constants that are used in the resource script. The 
resource compiler does not parse this casting syntax. For example, the following 
statement may not be included: 


#define IDBUTTON1 (USHORT) 3 
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If casting is required for C source compilation, you may use two statements such as: 


#define IDBUTTON1 3 
#define CSRC_IDBUTTONI ( (USHORT) IDBUTTON1) 


#define name value 


This directive assigns the given value to name. All subsequent occurrences of name 
are replaced by the value. 


name is any combination of letters, digits, or punctuation. 
value is any integer, character string, or line of text. 
Example: 


#define nonzero 1 
#define USERCLASS  "MyControlClass" 


#undef name 


This directive removes the current definition of name. All subsequent occurrences of 
name are processed without replacement. 


name is any combination of letters, digits, or punctuation. 
Example: 


#undef nonzero 
#undef USERCLASS 


#ifdef name 


This directive performs a conditional compilation of the resource file by checking the 
specified name. If the name has been defined using a #define directive, #ifdef directs 
the resource compiler to continue with the statement immediately after it. If the name 
has not been defined, #ifdef directs the compiler to skip all statements up to the next 
#endif directive. 


name is the name to be checked by the directive. 
Example: 
#ifdef Debug 


FONT 4 errfont.fnt 
#endif 


#ifndef name 


This directive performs a conditional compilation of the resource file by checking the 
- specified name. If the name has not been defined or if its definition has been removed 
using the #undef directive, #ifndef directs the resource compiler to continue processing 
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statements up to the next #endif, #else, or #elif directive, then skip to the statement after 
the #endif. If the name is defined, #ifndef directs the compiler to skip to the next #endif, 
#else, or #elif directive. 


name is the name to be checked by the directive. 


Example: 


#ifndef Optimize 
FONT 4 errfont. fnt 
#endif 


#if constant expression 


This directive performs a conditional compilation of the resource file by checking the 
specified constant-expression. If the constant-expression is nonzero, #if directs the 
resource compiler to continue processing statements up to the next #endif, #else, or #elif 
directive, then skip to the statement after the #endif. If the constant-expression is zero, 
#if directs the compiler to skip to the next #endif, #else, or #elif directive. 


constant expression is a defined name, an integer constant, or an expression 
consisting of names, integers, and arithmetic and relational operators. 


Example: 


#if Version<3 
FONT 4 errfont.fnt 
#endif 


#elif constant expression 


This directive marks an optional clause of a conditional compilation block defined by an 
#ifdef, #ifndef, or #if directive. The directive carries out conditional compilation of the 
resource file by checking the specified constant-expression. If the constant-expression 
is nonzero, #elif directs the resource compiler to continue processing statements up to 
the next #endif, #else, or #elif directive, then skip to the statement after the #endif. If 
the constant-expression is zero, #elif directs the compiler to skip to the next #endif, 
#else, or #elif directive. Any number of #elif directives can be used in a conditional 
block. 


constant expression is a defined name, an integer constant, or an expression 
consisting of names, integers, and arithmetic and relational operators. 


Example: 


#if Version<3 
FONT 4 italic.fnt 
#elif Version<7 
FONT 4 bold. fnt 
#endif 
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#else 


This directive marks an optional clause of a conditional compilation block defined by an 
#ifdef, #ifndef, or #if directive. The #else directive must be the last directive before 
#endif. 


Example: 


#ifdef Debug 

FONT 4 italic.fnt 
#else 

FONT 4 bold. fnt 
#endif 


#endif 


This directive marks the end of a conditional compilation block defined by an #ifdef, 
#ifndef, or #if directive. One #endif is required for each #ifdef, #ifndef, and #if directive. 


Multiple-Line Statements 
This sections covers “Code Page Flagging,” “Keyboard Resources” on page 31-10, and the 
following multiple-line statements: 


“ACCELTABLE Statement” on page 31-10 
“ASSOCTABLE Statement” on page 31-12 

“MENU Statement” on page 31-16 

“STRINGTABLE Statement” on page 31-22 

“Dialog and Window Template Statements” on page 31-13 


Code Page Flagging: The CODEPAGE statement may be placed within the source, to 
set the code page used for these resources: 


¢ ACCELTABLE 

e MENU 

e STRINGTABLE 

¢ DIALOGTEMPLATE and WINDOWTEMPLATE. 


The CODEPAGE statement cannot be encoded within any other statement. All items 
following a CODEPAGE statement are assumed to be in that code page. The code page is 
encoded in the resource, and the data in the resource is assumed to be in the specified code 
page. However, no checking is performed. 


These code pages can be specified: 


437 
850 
860 
863 
865. 


if the code page is not specified, code page 850 is assumed. 
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Keyboard Resources 
RT_FKALONG (=17), is defined in BSEDOS.H, and the resource compiler (RC.EXE) 
recognizes FKALONG. This type identifies a 256-byte table, that can be used for either 
primary or secondary scan-code mapping. 


The resource ID contains three bytes, the least significant byte identifying the type of 
scan-code mapping table as follows: 

0 Primary scan-code mapping 

1 Secondary scan-code mapping. 


The other two bytes are 0 for the primary mapping table, and the keyboard ID (as defined in 
PMWINP.H) for secondary mapping tables. This is to enable simple support to be provided 
for future keyboards with conflicting scan codes. 


The primary scan-code mapping table in the interrupt handler is stored as a resource of this 
type. The secondary scan-code mapping table in the interrupt handler is also stored as a 
resource of this type. 


Depending on which keyboard is attached, the resources are loaded when the system is 
initialized, and transferred to RING-O byte arrays, where they can be accessed by the 


interrupt handler as necessary. A default primary scan-code mapping table is transferred if 
the resource cannot be loaded. 


ACCELTABLE Statement 
The ACCELTABLE statement defines a table of accelerator keys for an application. 


An accelerator is a keystroke defined by the application to give the user a quick way to 
perform a task. The WinGetMsg function automatically translates accelerator messages from 
the application queue into WM_COMMAND, WM_HELP, or WM_SYSCOMMAND messages. 
The ACCELTABLE statement has the form: 

ACCELTABLE statement 


a aoa (ATE im iene 
id emoption 


a eS Se 


4 ll, 
keyval cmd 


»>——END—>« 


- id (USHORT) 
The resource identifier. 
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memoption 
Optional. It consists of the following keyword or keywords, specifying whether the ~ 
resource is fixed or movable, and whether it can be discarded: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact memory. 
DISCARDABLE Resource can be discarded if no longer needed. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION. 


keyval (USHORT) 
The accelerator character code. This can be either a constant or a quoted character. If 
it is a quoted character, the CHAR acceloption is assumed. If the quoted character is 
preceded with a caret character (*), a control character is specified as if the CONTROL 
acceloption had been used. 


cmd (USHORT) 
The value of the WM_COMMAND, WM_HELP, or WM_SYSCOMMAND message 
generated from the accelerator for the indicated key. 


acceloption (B/T_ 16) 
Defines the kind of accelerator. 


The following options are available: 


ALT 

CHAR 
CONTROL 
HELP 
LONEKEY 
SCANCODE 
SHIFT 
SYSCOMMAND 
VIRTUALKEY. 


The VIRTUALKEY, SCANCODE, LONEKEY, and CHAR acceloptions specify the type of 
message that matches the accelerator. Only one of these options can be specified for 
each accelerator. For information on the corresponding KC_* values, see WM_CHAR. 


The acceloptions SHIFT, CONTROL, and ALT, cause a match of the accelerator only if 
the corresponding key is down. 


lf there are two accelerators that use the same key with different SHIFT, CONTROL, or 
ALT options, the more restrictive accelerator should be specified first in the table. For 
example, Shift-Enter should be placed before Enter. 


The SYSCOMMAND acceloption causes the keystroke to be passed to the application 
as a WM_SYSCOMMAND message. The HELP acceloption causes the keystroke to be 
passed to the application as a WM_HELP message. [If neither is specified, a 
WM_COMMAND message is used. 


Example: 
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ACCELTABLE MainAcc 
BEGIN 
VK_F1,101,HELP 
VK_F3,102,SYSCOMMAND 
END 


This generates a WM_HELP with value 101 from VIRTUALKEY accelerator F1 and a 
WM_SYSCOMMAND with value 102 from VIRTUALKEY accelerator FS. 


ASSOCTABLE Statement 
The ASSOCTABLE statement defines the extended attributes (EA) for an application. 


The ASSOCTABLE statement has the form: 


ASSOCTABLE statement 
»——-ASSOCTABLE—assoctab1eid——____—___> 


>——BEGIN-———__—__—__________—______» 


>—-assocname,extensi neete 
flags icon 


»——-END—>< 


The source for the ASSOCTABLE description is contained in the resource file for a particular 
project: 


ASSOCTABLE assoctableid 

BEGIN 

“association name", "extension", flags, icon. filename 
"association name", "extension", flags, icon filename 


END 
association name 


Program recognizes data files of this EA TYPE. This is the same name found in the 
TYPE field of data files. 


assoctableid 
A name or number used to identify the assoctable resource. 


extension . 
3 letter file extension that is used to identify files of this type if they have no EA TYPE 
entry. (This may be empty.) 


flags 
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EAF_DEFAULTOWNER 
The default application for the file. 


EAF_UNCHANGEABLE 
This flag is set if the entry in the ASSOCTABLE is not to be edited. 


EAF_REUSEICON 
This flag is specified if a previously defined icon in the ASSOCTABLE is to be 
reused. Entries with this flag set have no icon data defined. The icon used for this 
entry is the icon used for the previous entry (see below). Note that EAF_* flags may 
be ORed together when specified in the ASSOCTABLE. 


icon filename 
Filename of the icon used to represent this file type. (This may be empty.) 


Example 


ASSOCTABLE 3000 

BEGIN 

"Product XYZ Spreadsheet", "“xys", EAF_DEFAULTOWNER, xyzspr.ico 
"Product XYZ Chart", "xyc", EAF_DEFAULTOWNER | EAF_REUSEICON 
END 


Dialog and Window Template Statements 
This section describes how to define dialog and window templates. 


It also describes the control data and presentation parameter structures that the application 
needs to create windows and define dialog templates. 


DLGTEMPLATE and WINDOWTEMPLATE statements are used by an application to create 
predefined window and dialog resource templates. These siaiernents are treated identically 
by the resource compiler and have the following format: 


DLG and WINDOW TEMPLATE —————————-------—--— 


sa Ed d————— 
WINDOWTEMPLATE: 


—— 


i-codapage— 


»>—BEGIN--;---DIALOG statement— END 
r—CONTROL. Sates) 
~~—-WINDOW statemen:- 


In the following description of the parts of the DLGTEMPLATE and WINDOWTEMPLATE 
statements, data types are shown after each parameter or option. These are the data types 
that the parameter or option is converted to when it is compiled. 


Purpose 
The DLGTEMPLATE or WINDOWTEMPLATE statement marks the beginning of a 
window template. It defines the name of the window, and its memory and load options. 


Chapter 31. Resource Files 31-13 


resourceid (USHORT) 
Either a unique name or an integer number identifying the resource. 


loadoption (LOADOPTION) 
The default is LOADONCALL. 


' See “Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION. 


memoption (MEMOPTION) 
The default is MOVEABLE. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
MEMOPTION. 


code page (USHORT) 
The code page of the text in the template. 


Alternatively, ({) can be used in place of BEGIN and (}) in place of END. 
. The DLGTEMPLATE ad WINDOWTEMPLATE keywords are synonymous. 


The DIALOG statement defines a dialog-box window that can be created by an application 
and has the following format: 


pire statement 


Ley ee 
control 


a a | 


>—BEGIN DIALOG—statement 
|~conrroL-statenent 
WINDOW-statement 
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The WINDOW and CONTROL statements have the format: 
WINDOW and CONTROL statements 


mre NDen | text »—-id,-x,—y,—-Cx,—-cy,-class—> 
CONTROL 


© LT ystyie— 
control 


a es 


»>—BEGIN DIALOG—statement 
[contro L—-statement 
WINDOW-statement 


Note: The WINDOW and CONTROL keywords are synonymous. 


The DIALOG, CONTROL, and WINDOW statements between the BEGIN and END 
statements are defined as child windows. Presentation parameters always apply to the 
whole control. They cannot be changed for the individual items within the control. 


Following is the description of the parameters for these statements. 


Purpose 
These statements mark the beginning of a window. They define the starting location on 
the display screen, its width, its height, and other details such as style. 


Note: Not all values may be specified for each statement type. For details, see the call 
syntax diagrams. 


text (PCH) 
A string, enclosed in double quotes, that is displayed in the title-bar control, if it exists. 
To insert a double-quote character (") in the text, use two double-quote characters (“). 


id (USHORT) 
Item identifier. 


x,y (SHORT) 
Integer numbers specifying the x- and y-coordinates on the display screen of the lower 
left corner of the dialog. X and y are in dialog coordinates. The exact meaning of the 
coordinates depends on the style defined by the style argument. For normal dialogs, the 
coordinates are relative to the origin of the parent window. For FCF_SCREENALIGN 
style boxes, the coordinates are relative to the origin of the display screen. With 
FCF_MOUSEALIGN, the coordinates are relative to the position of the pointer at the time 
the dialog is created. | 
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cx,cy (SHORT) 
Integer numbers specifying the width and height of the window. 


class (PCH) 
The class of the window or contro! to be created. 


Note: For a DIALOG statement the class is fixed as WC_FRAME and cannot be 
specified. 
style (ULONG) . 
Any additional window style, frame style, or other class-specific style. 
The default style is WS_SYNCPAINT | WS_CLIPSIBLINGS | WS_SAVEBITS | 


FS_DLGBORDER. If the FS_DLGBORDER or WS_SAVEBITS styles are not required, 
they should be preceded by the keyword “NOT.” For example: 


NOT FS _DLGBORDER | FS_BORDER | NOT WS _SAVEBITS 


replaces the FS_DLGBORDER default style by the FS_BORDER style and removes the 
WS_SAVEBITS style. Note that the logic of the NOT keyword is different from the 
corresponding operator in the C language. 


It is not possible to remove the default WS_SYNCPAINT and WS_CLIPSIBLINGS styles. 
control (ULONG) 
Frame Creation Flags (FCF_*; see page 13-1) for the window 


This data is placed in the control data field in the correct format for a window of class 
WC_FRAME. 


Note: FCF_SHELLPOSITION has no effect if specified in a template. 


CTLDATA Statement 
A statement used to define control data for the control. For more information on this 
statement, see “Control Data Statement” on page 31-28 


PRESPARAMS Statement 
A statement used to define presentation parameters. For more information on this 
statement, see “Presentation Parameters Statement” on page 31-28 


MENU Statement 

The MENU statement defines the contents of a menu resource. A menu resource is a 
collection of information that defines the appearance and function of an application menu. A 
menu can be used to create an action bar. 
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The MENU statement has the form: 


MENU statement 


p>>—MENU-menui a ea reel) eon ea 
loadoption emoption 
LS seaepane= 


a eo 

»>——BEGIN 

iieiad Uhr 
SUBMENU-statement: 


menuid (USHORT) 
A name or number used to identify the menu resource. 


loadoption (LOADOPTION) 
The default is LOADONCALL. 


See“Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION. 


memoption (MEMOPTION) 
The default is MOVEABLE. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
MEMOPTION. 


codepage (USHOAT) 
The code page of the text. 


PRESPARAMS statement 
A special resource statement used to define presentation parameters. These are 
discussed in more detail in “Presentation Parameters Statement” on page 31-28. 


MENUITEM statement 
A special resource statement used to define the items in the menu. These are discussed 
in more detail in “Menu Item Statements” on page 31-18. 


SUBMENU statement 
A special resource statement used to define a submen. SUBMENU statements are 
discussed in more detail in “Submenu Statements” on page 31-19. 
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Example: Following is an example of a complete MENU statement: 


MENU sample 
BEGIN 
MENUITEM "“Alpha", 100, MIS TEXT 
SUBMENU "“Beta", 101, MIS_TEXT 
BEGIN 
MENUITEM "“Green", 200, MIS TEXT 
MENUITEM "“Blue", 201, MIS _TEXT,MIA_CHECKED 
END 
END 


Menu Item Statements: MENUITEM statements are used in the item-definition section 
of a MENU statement to define the names and attributes of the actual menu items. Any 
number of statements can be given; each defines a unique item. The order of the 
statements defines the order of the menu items. 


Note: The MENUITEM statements can only be used within an item-definition section of a 
MENU statement. 


MENUITEM statement 
» >>—MENULT EM __—_—__—__—_———_» 


stri N= ok 
| Lsty es ee me | 
SEPARATOR 


string (PCH) 
A string, enclosed in double quotation marks, specifying the text of the menu item. 


To insert a double-quote character (") in the text, use two double-quote characters (""). 


If the styles parameter does not contain MIS_TEXT, the string is ignored but must still be 
specified. An empty string ("") should be specified in this instance. 


To indicate the mnemonic for each item, insert the tilde character (7) in the string 
preceding the mnemonic character. 


For MENUITEM statements within a SUBMENU (that is, pull-down menus) text may be 
split into a second column with an alignment substring. To right-align items insert “\a” in 
the text where alignment should begin. To left-align a second column of text insert “\t” in 
the text where alignment should begin. For each SUBMENU the longest item in the 
second column determines the width of that column. Only one alignment substring 
should be used in a menu item. 


cmd (USHORT) 
The value of the WM_COMMAND, WM HELP, or WM_SYSCOMMAND message 
generated by the item when it is selected. It identifies the selection made and should be 
unique within one menu definition. 
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styles (USHORT) ; 
One or more menu options defined by the MIS_* constants, ORed together with the “|” 
operator. For definitions of the MIS_* constants, see “Menu Item Styles” on page 15-2. 


attributes (USHORT) 
; One or more menu options defined by the MIA_* constants, ORed together with the “|” 
operator. For definitions of the MIA_* constants, see “Menu Item Attributes” on 
page 15-3. 


The style MIS_ SUBMENU must not be used with this statement. See “Submenu 
Statements” for the SUBMENU statement. 


Examples: 


MENUITEM “Alpha", 1, MIS_TEXT,MIA_ENABLED|MIA_CHECKED, 'A' 
MENUITEM "Beta", 2, MIS_TEXT,,'B' 


Submenu Statements: _|n addition to simple items, a menu definition can contain the 
definition of a submenu. A submenu can itself invoke a lower level submenu. 


SUBMENU statement 
p>>—SUBMENU 


Prine oa eect eal 
cmd styles attributes 


i ere 

>——BEGIN 

ae a RL 
SUBMENU-statement 


string (PCH) 
A string, enclosed in double quotation marks, specifying the text of the menu item. 


To insert a double-quote character (") in the text, use two double-quote characters (""). 


If the styles parameter does not contain MIS_TEXT, the string is ignored but must still be 
specified. An empty string (“’) should be specified in this instance. 


cmd (USHORT) 
The value of the WM_COMMAND, WM_HELP, or WM_SYSCOMMAND message 
generated by the item when it is selected. It identifies the selection made and should be 
unique within one menu definition. 
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styles (USHORT) 
One or more menu options defined by the MIs constants, ORed together with the “| 
operator. 


In the SUBMENU statement, the style MIS_SUBMENU is always ORed with the styles 
given. If no value is supplied, the default value of MIS_TEXT and MIS_SUBMENU is 
used. 


attributes (USHORT) 
One or more menu options defined by the MIA_ constants, ORed together with the | 
operator. 


Example: 


MENU chem 
BEGIN 


SUBMENU "“Elements", 2, MIS_TEXT 

BEGIN 
MENUITEM "“Oxygen", 200, MIS_TEXT 
MENUITEM ““Carbon", 201, MIS_TEXT,MIA_ CHECKED 
MENUITEM "“Hydrogen", 202, MIS_TEXT 

END 


SUBMENU "“Compounds", 3, MIS_TEXT 

BEGIN 
MENUITEM "“Glucose", 301, MIS_TEXT 
MENUITEM “~Sucrose", 302, MIS_TEXT,MIA_CHECKED 
MENUITEM "Lactose", 303, MIS _TEXT|MIS_BREAK 
MENUITEM "“Fructose", 304, MIS_TEXT 

END 


END 


SEPARATOR Menu Item: There is a special form of the MENUITEM statement that is 
used to create a horizontal dividing bar between two active menu items in a pull-down menu. 
The SEPARATOR menu item is itself inactive and has no text associated with it nor a cmd 
value. 


Example 


MENUITEM "Roman", 206, MIS_TEXT 
MENUITEM SEPARATOR 
MENUITEM "20 ~Point", 301, MIS TEXT 


Menu Template: Menu templates are data structures used to define menus. Menu 
templates can be loaded as resources or created dynamically, or embedded in dialog 
templates, which in turn can be loaded as resources or created dynamically. Templates 
loaded as resources cannot contain references to bit maps or owner-drawn items. A menu 
template consists of a sequence of variable-length records. Each record in a menu template 
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defines a menu item. If a menu item contains a reference to a submenu, the menu template 
that defines that submenu is placed after the definition of that particular menu item. 


Template Format: A menu template has the following format: 


Length (USHORT) 
The length of the menu template. 


Version (USHORT) 
The template version. Versions 0 and 1 are valid. 


Code page (USHORT) 
The identifier of the code page used for the text items within the menu (but not any 
submenus, which each have their own code pages). 


Item offset (USHORT) 
The offset of the items from the start of the template, in bytes. 


Count (USHORT) 
The count of menu items. 


Presentation parameters offset (USHORT) 
Offset of presentation parameters from the start of the template, in bytes. This field is 
only present for version 1 of the template. 


Menu Items 
A variable-sized array of menu items as follows: 


Style (USHORT) 
Menu item styles (MIS_*; see page 15-2) combined with the logical-OR operator. 


Attributes (USHORT) 
Menu item attributes (MIA_*; see page 15-3) combined with the logical-OR operator. 


Item (USHORT) 
An application-provided identifier for the menu item. 


» 


Variable data 
Following the identifier is a variable data structure whose format depends upon the 
value of Style: 


MIS_TEXT 


Text (PSZ) . 
Null-terminated text string. 


MIS_SUBMENU 
A menu template structure. 


MIS_BITMAP 


Text (PCH) 
Null-terminated text string. 
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For MIS_ BITMAP menu items, the item text string can be used to derive the 
resource identifier from which a bit map is loaded. There are three instances: 


¢ The first byte is null; that is, no resource is defined and it is assumed that 
the application subsequently provides a bit-map handle for the item. 


¢ The first byte is OxFF, the second byte is the low byte of the resource 
identifier, and the third byte is the high byte of the resource identifier. 


¢ The first character is “#,” and subsequent characters make up the decimal 
text representation of the resource identifier. 


The resource is assumed to reside in the resource file of the current process. 


If the string is empty or does not follow the format above, no resource is 
loaded. 


STRINGTABLE Statement 

The STRINGTABLE statement defines one or more string resources for an application. 
String resources are null-terminated ASCII strings that can be loaded, when needed, from 
the executable file, using the WinLoadString function. 


Note: The ASCII strings can include no more than 256 characters, including the NULL 
termination character. : 


The STRINGTABLE statement has the form: 


STRINGTABLE statement 


i aca ener eer | DRS rea Aad 
loadoption emoption 


>——-BEGIN——string-definitions——END—»>< 


String-definitions 


>>———integer———string 


loadoption (LOADOPTION) 
' An optional keyword specifying when the resource is to be loaded. It must be one of: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 


The default is LOADONCALL. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
LOADOPTION. 
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memopuer (MEMOPTION) 


Consists of the following keyword or keywords, specifying whether the resource is fixed 
or movable and whether it is discardable: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE _ Resource can be moved if necessary to compact memory. 
DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 


See “Resource Load and Memory Options” on page 31-2 for a description of 
MEMOPTION. 


string (PCH) 


A string, enclosed in double quotation marks. To insert a double- -quote character (") in 
the text, use two double-quote characters (""). 


Note: A string may be defined on more than one line if each line begins and ends with 
a double-quote. If newline characters are desired after each line, there should be 
a double-quote at the beginning of the first line and at the end of the last line 
only. 


The string may contain any ASCII characters. Because (\) is interpreted as an escape 
character, use (\\) to generate a (\). 


The following escape sequences may be used: 


Escape 

Sequence Name 

\t Horizontal tab 
\a 
Bell (alert) 

\nnn ASCII character (octal) 
\xdd 


ASCII character (hexadecimal). 


The sequences \ddd and \xdd allow any character in the ASCII character set to be 
inserted in the character string. Thus, the horizontal tab could be entered as \X09, \011 
or \t. 


Example 


#define IDS STRING] 1 
#define IDS STRING2 2 
#define IDS STRING3 3 


STRINGTABLE 

BEGIN 
IDS_STRING1, "The first two strings in this table are identical." 
IDS_STRING2, "The first two strings " 


"in this table are identical." 


IDS_STRING3, "This string will contain a newline character 


END 


before it continues on this line." 
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Templates, Control Data, and Presentation Parameters 


Dialog Template 
A dialog template is a data structure used to define a dialog box. Dialog templates can be 
loaded from resources or created dynamically in memory. Dialog templates define windows 
of any window class that contain child windows of any class. For standard dialog windows, 
the dialog window itself is created with the WC_FRAME class, and its children are any of the 
preregistered control classes. 


The dialog template specifies all the information required to create a dialog box and its 
children. 


Dialog Coordinates 
Coordinates in a dialog template are specified in dialog coordinates. These are based on the 
default character cell size; a unit in the horizontal direction is 1/4 the default character-cell 
width, and a unit in the vertical direction is 1/8 the default character-cell height. The origin is 
the bottom left-hand corner of the dialog box. 


Dialog Template Format and Contents 
A dialog template has these sections: 


Header Defines the type of template format and contains information about the 
location of the other sections of the template. It also contains a summary of 
the status of the individual controls contained within the dialog box. 


Items Defines each of the controls that comprise the dialog box. 


Data area Contains the data values associated with each control. Each control defined 
in the item section contains pointers to the data area section. The data area 
also contains presentation parameter definitions. The data area is not 
necessarily a contiguous portion of the template. User data can be placed 
anywhere in the template if it does not interfere with other defined information. 


The sections of a dialog template are illustrated in Figure 31-1 on page 31-25. 


Notes: 


1. Throughout the dialog template all lengths are in bytes. String lengths do not include 
any null terminator that may be present. When strings are passed to the Presentation 
Interface, the length specifications are used and any null terminators are ignored. When 
strings are returned by the Presentation Interface, length specifications and null 
terminators are both supplied; therefore, space must be allowed for a null terminator. 


2. All offsets are in bytes from the start of the dialog template structure. 
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Header 


Template Length 


Template Type 


Code Page 


Reserved 


Items 


Dialog Box Control Window 


Control Window Descriptor 


Control Window Descriptor 
Child Control Window Descriptor 
Child Control Window Descriptor 


Control Window Descriptor 


Data Area 


Text 


Control data 


Figure 31-1. Dialog Template 
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Header 7 
The dialog template header consists of: 


Template length (USHORT) 
The overall length of the dialog template. 


Template type (USHORT) . 
The dialog template format type. The format defined is type 0. 


Code page (USHORT) 
The code page of the text in the dialog template. | 


Items offset (USHORT) 
The offset of the array of dialog items. 


Reserved (USHORT) 
Must be 0. 


Focus item (USHORT) 
The index in the array of dialog items of the control to receive the focus. If this value is 0, 
or if the identified contro! cannot receive the focus, for example because it is a static 
control, the focus is passed to the first item within the template.that can receive the focus. 


Reserved (USHORT) 
Must be 0. 


Items | 


The dialog tempiate items are specified as elements of an array that also defines the 
hierarchy of the control windows of the dialog box. Each element of the array is a control 
window descriptor and defines some control or a child of some control, so that every control 
within the dialog box is described by this array. The first descriptor is the specification of the 
dialog box itself. 


The dialog template items consist of: 


Reserved (USHORT) (BOOL16) 
Must be 0. 


Children (USHORT) 
The number of dialog item child windows that are owned by this dialog item. 


This is the number of elements following in the array that are created as child windows of 
this window. Each window can have any number of child windows, which allows for a 
tree-structured arrangement. 


For example, in Figure 31-1 on page 31-25, assuming that there are no more dialog items 
than are shown, the first item, the dialog box control window descriptor, has three children. 
The second item has no children, the third item has two children, and the remaining three 
items have no children. , 
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Class name length (USHORT) 
The length of the window class name string. 


Class name offset (USHORT) 
The offset of the window class name string. 


Text length (USHORT) 
The length of the text string. 


For controls that allow input of text, this is the current text length, not the maximum text 
length, and so this value changes when text is put into the control. 


Text offset (USHORT) 
The offset of the text string. 


Style (ULONG) (BOOL32) 
The window style of the control. 


The standard style bits are 16 bits. The use of the remaining 16 bits depends on the class 
of the control. 


x (SHORT) 

y (SHORT) 
The position of the origin of the dialog item. This is specified in dialog coordinates, with x 
and y relative to the origin of the parent window. 


cx (SHORT) 
cy (SHORT) . 
The size of the dialog item in dialog coordinates; it must be greater than 0. 


Identifier (USHORT) 
An application-defined identifier for the dialog item. 


Reserved (USHORT) 
Must be zero. 


Control data offset (USHORT) 
The offset of the control-specific data for this dialog item. A value of 0 indicates that there 
is no control data for this dialog item. 


Data Area 
The dialog template data area contains the following different types of objects: text, class 
name, presentation parameters, and control data. These objects can be placed anywhere 
within the data area. They do not have to be in contiguous storage, and so an application 
can place data for its own use between these objects. 


The dialog template data area contains: 


Text (PCH) 
The textual data associated with a dialog item. 


Class name (PCH) 
The name of the window class. 
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Presentation parameters (PRESPARAMS) 
Presentation parameters are defined in “Presentation Parameters Statement” on 
page 31-28. 


Control data (CTLDATA) 
For more information, see “Control Data Statement.” 


Control Data Statement 


The optional CTLDATA statement is used to define control data for the control. Hexadecimal 
or decimal word constants follow the CTLDATA statement, separated with commas. . 


CTLDATA statement 


pe>—CTLDATA decimal—value 
hexadecimal—value 


string 


In addition to hexadecimal or decimal data, the CTLDATA statement can be followed by the 
MENU keyword, followed by a menu template in a BEGIN/END block. This creates a menu 
template as the contro! data of the window. 


Presentation Parameters Statement 


The optional PRESPARAMS statement is used to define presentation parameters. The 
syntax of the PRESPARAMS statement is as follows. 


PRESPARAMS statement 


a oe 2 


A presentation parameter consists of: 


type (ULONG) 
The presentation parameter attribute type. See the PARAM data type for a description of 
valid types. 


A string can be used to specify the type for a user type. If this is done, the string type is 
converted into a string atom when the dialog template is read into memory. Thereafter, 
this presentation parameter is referred to by this string atom. The application can use the 
atom manager API to match the string and the string atom. 
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value (LONG or PSZ) 
One or more values depending upon the attribute type. 


if the value is enclosed in quotes it is a zero-terminated string. Otherwise, it is converted 
to a LONG. There may be more than one value, depending upon the type. See PARAM 
data type for a description of the values required for system-defined presentation 
parameters. 


Examples: The following are examples of PRESPARAMS statements: 


PRESPARAMS PP_BORDERCOLOR, OxO00ffOOffL 
PRESPARAMS PP_FONTNAMESIZE, "12.Helv" 

PRESPARAMS "my color", OxO0f FOOFFL 

PRESPARAMS "my param", 0, 1, 2, 3, "Hi there" 


Parent/Child/Owner Relationship 
The format of the DLGTEMPLATE and WINDOWTEMPLATE resources is very general to 


allow tree-structured relationships within the resource format. The general layout of the 
templates is: 


WINDOWTEMPLATE id 


BEGIN 
WINDOW winTop the top-level window 
BEGIN 
WINDOW wind1 
WINDOW wind2 
WINDOW wind3 
BEGIN 
WINDOW wind4 
END 
WINDOW wind5 
END 
END 


In this example, the top-level window is identified by winTop. It has four child windows: 
wind1, wind2, wind3, and wind5. wind3 has one child window, wind4. When each of 
these windows is created, the parent and the owner are set to be the same. 


The only time when the parent and owner windows are not the same is when frame controls 
are automatically created by a frame window. 


Note that the WINDOW statements in the example above could also have been CONTROL 
or DIALOG statements. 
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Predefined Window Classes 


The CONTROL statement can be used to define a window control of any class. Window 
classes may be user defined of one of a predefined set provided by the operating system. 
The following classes are provided in the OS/2 operating system. 


WC_FRAME 
WC_ STATIC 
WC_BUTTON 
WC_COMBOBOX 
WC_ENTRYFIELD 
WC_MLE 
WC_LISTBOX 
WC_MENU 
WC_SCROLLBAR 
WC_TITLEBAR 
WC_SPINBUTTON 
WC_CONTAINER 
WC_SLIDER 
WC_VALUESET 
WC_ NOTEBOOK 


Application frame control. 

Text and group boxes. 

Push button, check box or radio button. 
Combination of an entry field and list box. 
Single line entry field. 

Multiple line entry field. 

List box. 

Application action bar, menus and popup menus. 
Horizontal or vertical scroll bar. 
Application title bar. 

Spin button entry field. 

Container list. 

Horizontal or vertical slider control. 

Value set control. 

Notebook control. 


These controls make up the standard user interface components for applications. The 


following example shows a simple listbox control. 


CONTROL "", 1, 10, 20, 60, 40, WC_LISTBOX, WS_VISIBLE 


Predefined Control Statements | 
In addition to the general form of the CONTROL statement, there are special control 
statements for commonly used controls. These statements define the attributes of the child 
control windows that appear in the window. 


Control statements have this general form: 


Control statements 


>>—control type—-text—,—id—,—x—,—y—,-CX—, -Cy > 


eer eee 


»>—~BEGIN DIALOG statement 
CONTROL statement 
WINDOW statement 
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The following six controls are exceptions to this form because they do not take a text field. 
See the LISTBOX control statement for the form of these six controls. 


CONTAINER 
LISTBOX 
NOTEBOOK 
SLIDER 
SPINBUTTON 
VALUESET 


controltype 
is one of the keywords described below, defining the type of the control. 


text (PCH) 
is a string specifying the text to be displayed. The string must be enclosed in double 
quotation marks. The manner in which the text is displayed depends on the particular 
control, as detailed below. 


To indicate the mnemonic for each item, insert the tilde character (") in the string 
preceding the mnemonic character. 


The double quotation marks are required for the COMBOBOx< title even if no title is used. 


id (USHORT) 
is a unique integer number identifying the control. 


xy (SHORT) 
are integer numbers specifying the x- and y-coordinates of the lower left corner of the 
control, in dialog coordinates. The coordinates are relative to the origin of the dialog. 


cx,cy (SHORT) 
are integer numbers specifying the width and height of the control. 


The x, y, cx, and cy fields can use addition and subtraction operators (+ and -). For 
example, 15 + 6 can be used for the x-field. 


Styles can be combined using the (|) operator. 


The control type keywords are shown below, with their classes and default styles: 
AUTOCHECKBOX 


Class WC_BUTTON 
Default style WS_TABSTOP, WS_VISIBLE, BS_AUTOCHECKBOX 


AUTORADIOBUTTON 


Class WC_BUTTON 
Default style BS_AUTORADIOBUTTON, WS_TABSTOP, WS_VISIBLE 


CHECKBOX 


Class WC_BUTTON 
- Default style BS_ CHECKBOX, WS_TABSTOP, WS_VISIBLE 


Chapter 31. Resource Files 31-31 


31-32 


COMBOBOX 


Format 


Class 
Default style 


CONTAINER 


Format 


Class 
Default style 


CTEXT 


lass 
Default style 


DEFPUSHBUTTON 


Class 
Default style 


EDITTEXT 


Class 
Default style 


ENTRYFIELD 


Class 
Default style 


FRAME 


Class 
Default style 


GROUPBOX | 


Class 
Default style 


ICON 


Class 
Default style 


The form of the COMBOBOX control statement is shown below. 
The fields have the same meaning as in the other control statements. 


COMBOBOX statement 
»>>—COMBOBOX—"title"—,—id—_, —_x—- ,—_y—_-, —— 


>——_ cy 


»——style 


WC_COMBOBOX 
CBS_SIMPLE, WS_TABSTOP, WS_VISIBLE 


The CONTAINER control statement does not contain a text field, so it 
has the same format as the LISTBOX statement. 

WC_CONTAINER 

WS_TABSTOP, WS_VISIBLE, CCS_SINGLESEL 


WC_STATIC 
SS_TEXT, DT_CENTER, WS_GROUP, WS_VISIBLE 


WC_BUTTON 
BS_DEFAULT, BS_ PUSHBUTTON, WS_TABSTOP, WS_VISIBLE 


WC_ENTRYFIELD 
WS_ENTRYFIELD, WS_TABSTOP, WS_VISIBLE, ES_AUTOSCROLL 


WC_ENTRYFIELD 
WS_TABSTOP, ES_LEFT, WS_VISIBLE 


WC_FRAME 
WS_VISIBLE 


WC_STATIC | 
SS_GROUPBOX, WS_TABSTOP, WS_VISIBLE 


WC_STATIC | 
SS_ICON, WS_VISIBLE 
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LISTBOX 


Format 


Class 
Default style 


LTEXT 


Class 
Default style 


MLE 


Class 
Default style 


NOTEBOOK 


_ Format 


Class 
Default style 


PUSHBUTTON 


Class 
Default style 


RADIOBUTTON 


Class 
Default style 


RTEXT 


. Class 
Default style 


SLIDER 


Format 


Class 
Default style 


The form of the LISTBOX control statement is different from the general 
form because it does not take a text field, however the fields have the 
same meaning as in the other control statements. The form of the 
LISTBOX control statement is shown below. 


LISTBOX statement 


>>—control type —_id-—_,§ —x—_ yo 


p>—,—_cy 


»— style 


WC_LISTBOX | 
LBS NOTIFY, LBS_SORT, WS_VSCROLL, WS_BORDER, 
WS_ VISIBLE 


WC_STATIC 
SS_TEXT, DT_LEFT, WS_GROUP, WS_VISIBLE 


WC_MLE 
WS_MLE, WS_TABSTOP, WS_VISIBLE, MLS_BORDER 


The NOTEBOOK control statement does not contain a text field, so it 
has the same format as the LISTBOX statement. 

WC_NOTEBOOK 

WS_NOTEBOOK, WS_TABSTOP, WS_VISIBLE 


WC_BUTTON 
BS PUSHBUTTON, WS_TABSTOP, WS_VISIBLE 


WC_BUTTON 
BS_RADIOBUTTON, WS_TABSTOP, WS_ VISIBLE 


WC_STATIC 
SS_TEXT, DT_RIGHT, WS_GROUP, WS_VISIBLE 


The SLIDER control statement does not contain a text field, so it has 
the same format as the LISTBOX statement. 


WC_SLIDER 
WS_SLIDER, WS_TABSTOP, WS_VISIBLE - 
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SPINBUTTON 


Format The SPINBUTTON control statement does not contain a text field, so it 
has the same format as the LISTBOX statement. 


Class WC_SPINBUTTON 
Default style | WS_TABSTOP, WS_VISIBLE, SPBS_MASTER 
VALUESET 


Format The VALUESET control statement does not contain a text field, so it 
has the ‘same format as the LISTBOX statement. 


Class WC_VALUESET 
Default style WS_VALUESET, WS_TABSTOP, WS_VISIBLE 


Examples: The following is a complete example of a DIALOG statement: 


DLGTEMPLATE errmess 
BEGIN 
DIALOG "Disk Error", 100, 10, 10, 300, 110 
BEGIN 
CTEXT "Select One:", 1, 10, 80, 280, 12 
RADIOBUTTON "Retry", 2, 75, 50, 60, 12 
RADIOBUTTON "Abort", 3, 75, 30, 60, 12 
RADIOBUTTON "Ignore", 4, 75, 10, 60, 12 
END 
END 


This is an example of a WINDOWTEMPLATE statement that is used to define a specific kind 
of window frame. Calling Load Dialog with this resource automatically creates the frame 
window, the frame controls, and the client window (of class MyClientClass). 


WINDOWTEMPLATE wind1 
BEGIN 
FRAME "My Window", 1, 10, 10, 320, 130, WS VISIBLE, 
FCF_STANDARD | FCF_VERTSCROLL 


BEGIN 
WINDOW "", FID_CLIENT, 0, 0, 0, 0, "MyClientClass", 
style 
END 
END 
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This example creates a resource template for a parallel dialog identified by the constant 
paraliel1. It includes a frame with a title bar, a system menu, and a dialog-style border. The 
parallel dialog has three auto radio buttons in it. 


DLGTEMPLATE parallell 
BEGIN 
DIALOG "Parallel Dialog", 1, 50, 50, 180, 110 
CTLDATA FCF_TITLEBAR | FCF_SYSMENU | FCF_DLGBORDER 
BEGIN 
AUTORADIOBUTTON "Retry", 2, 75, 80, 60, 12 
AUTORADIOBUTTON "Abort", 3, 75, 50, 60, 12 
AUTORADIOBUTTON "Ignore", 4, 75, 30, 60, 12 
END 
END 


Resource (.RES) File Specification 
The format for the .RES file is: 


(/TYPE NAME FLAGS SIZE BYTES/)+ 


Where: 


TYPE is either a null-terminated string or an ordinal, in which instance the first byte is 
OxFF followed by an INT that is the ordinal. 


/* Predefined resource types */ 
#define RT POINTER 

#define RT_BITMAP 

#define RT_MENU 

#define RT DIALOG 

#define RT_STRING 

#define RT_FONTDIR 

#define RT FONT 

#define RT_ACCELTABLE 

#define RT_RCDATA 

#define RT_DLGINCLUDE 11 
#define RT_FKALONG 17 
#define RT_HELPTABLE 18 


OON DO FWD 


NAME | is the same format as TYPE. There are no predefined names. 
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FLAGS is an unsigned value containing the memory manager flags: 


#define NSTYPE 0x0007  /* Segment type mask */ 
#define NSCODE @x0000 /* Code segment */ 
#define NSDATA 0x0001 /* Data segment */ 
#define NSITER Q@x0008 /* Iterated segment flag */ 
#define NSMOVE 0x0010 /* Moveable segment flag x/ 
#define NSPURE Q@x0020 /* Pure segment flag x/ 
#define NSPRELOAD 0x004Q0 /* Preload segment flag */ 
#define NSEXRD Qx0080 /* Execute-only (code segment), */ 
/* or read-only (data segment) */ 
#define NSRELOC 0x0100 /* Segment has relocations x/ 
#define NSCONFORM 0x0200 /* Segment has debug info ~ x/ 
#define NSDPL @x0COO0 =/* 286 DPL bits */ 
#define NSDISCARD 0x1000 /* Discard bit for segment x/ 
#define NS32BIT Qx2000 © /* 32-BIT code segment x/ 
#define NSHUGE 0x4000 /* Huge memory segment */ 
SIZE is a LONG value defining how many bytes follow in the resource. 
BYTES is the stream of bytes that makes up the resource. 


Any number of resources can appear one after another in the .RES file. 
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Chapter 32. Code Pages 


The initialization file contains country information relating to date, time, and numeric formats. 
It does not contain code-page information; this is obtained from the CONFIG.SYS file. 


Applications start with the default code page. The default code page is set when the 
operating system is installed. It can be changed subsequently either by reinstalling the 
operating system or by editing the COUNTRY statement in the CONFIG.SYS file. 


A GPI presentation space inherits the code page of the process that created it. The code 
page changes only when the process calls GpiSetCp 


Windowed PM Applications 


Windowed PM applications allow the code-page calls to use any of the supported ASCII 
code pages. These are: 


Char. Set Code Page 
Canadian-French 993 863 
Desktop Publishing 1146 1004 
Iceland 991 861 
Latin 1 Multilingual 980 850 
Latin 2 Multilingual 982 852 
Nordic 995 865 
Portuguese 990 860 
Turkey 987 857 
U.S. (IBM PC) 919 437 


Code page 1004 is compatible with Microsoft** Windows™. 


© Copyright IBM Corp. 1994 32-1 


32-2 


The following EBCDIC code pages, based on character set 697, are also available for output: 


Char. Set Code Page 

Austrian/German 697 273 
Belgian 697 500 
Brazil 697 037 
Czechoslovakia 959 870 
Danish/Norwegian 697 277 
Finnish/Swedish * 697 278 
French 697 297 
Hungary 959 870 
Iceland 697 871 
International 697 500 
Italian 697 280 
Poland 959 870 
Portuguese 697 037 
Spanish 697 284 
Turkey 1152 1026 
U.K.-English 697 285 
U.S.-English 697 037 
Yugoslavia 959 870 


Note: Code pages 274 (Belgian) and 282 (Portuguese) can be used to provide access to 
old data. 


The operating system provides the following additional code-page setting and query calls for 
the supported ASCII and EBCDIC code pages. These calls work independently of the 
CONFIG.SYS file. 


GpiSetCp Sets the code page for GPI. 

GpiQueryCp Queries the code page for GPI. 
GpiCreateLogFont Creates fonts in a code page. 

WinSetCp Sets the code page for a message queue. 
WinQueryCp Queries the code page for a message queue. 


WinQueryCpList creates a list of code pages supported by the operating system. 


Text entered in a dialog box is supplied to the application in the code page of the queue 
(‘queue code page’). If possible, the code page of a resource (for example, a menu or dialog 
box) should match the code page of the queue. In general, code page 850 is the best 
choice for both an application and its resources. 


Applications should be able to process data from a variety of sources. Because code page 


850 contains most of the characters in other supported code pages, this is usually the best 
choice for the queue code page. 
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OS/2 Code Page Options for PM Applications 


Application 


CONFIG.SYS 
contains the 
default code 
page set by 
CODEPAGE= 


DosSetProcessCp (see note 1) 
Set code page for this process 
(keyboard/display not changed). 


WinQueryCpList (see note 2) 
| Query list of supported code pages. | 


WinSetCp, WinQueryCp (see note 1) 
Set or query code page for 
translating incoming messages 
(keystrokes) . 


: 


eno 


——| Message 
——]| queue 
piSetCp, GpiQueryCp (see note 2) 
| Set or query default GPI code page. | 
GpiCreateLogFont (see note 2) 
| Create font in a code page. | Display 


WinCpTranslateChar (see note 2) 
WinCpTranslateString (see note 2) 
Convert character or string from 
one code page to another. 


+——>Disk 


Note 1: Either of the two ASCII code pages specified in CONFIG.SYS. 
Code page 1004 is also supported. 

Note 2: Any supported ASCII or EBCDIC code page as reported by 
WinQueryCpList. 
Code page 1004 is also supported. 


Figure 32-1. OS/2 Code Page Options for PM Applications 
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OS/2 Font Support for Multiple Code Pages 


The operating system supports multiple code pages for text input and output. A single font 
resource is used to support all the code pages. This section describes the font resource 
format. 


Font Code-Page Functions 
Many of the characters required by each code page are common; for example, the first 128 
characters of all the ASCII code pages are identical. This set of characters is called the 
Universal Glyph List (UGL). A code page is simply a set of pointers into the UGL. 


As the characters in every font are in the same order, only one set of code-page translation 
tables is necessary. 


Note: The fonts of Microsoft Windows support only code page 1004. 


Font Layout | 
The following table lists the full character set in the order in which the characters occur in the 
multi-code-page font. Characters are listed in order of their universal glyph list (UGL) 
number; the graphic character global identifier (GCGID) and a description of each character 
are also given. 


UGL GCGID Description 
1 $S000000 Smiling face 
2 $S010000 Smiling face, reverse image 
3 $S020000 Heart suit symbol 
4 $S030000 Diamond suit symbol 
5 $S040000 Club suit symbol! 
6 $S050000 Spade suit symbol 
7 §M570000 __— Bullet 
8 SM570001 Bullet, reverse image 
9 SM750000 Open circle 
10 SM750002 Open circle, reverse image 
11 SM280000 Male symbol 
12 SM290000 Female symbol 
13. SM930000 _— Musical note 
14 SM910000 Two musical notes 
15 SM690000 Sun symbol 
16 SM590000 Forward arrow indicator 
17 SM630000 Back arrow indicator 
18 SM760000 Up-down arrow 
19 SP330000 Double exclamation point 
20 SM250000 Paragraph symbol (USA) 
21 SM240000 Section symbol (USA), paragraph (Europe) 
22 SM700000 Solid horizontal rectangle 
23 SM770000 Up-down arrow, perpendicular 
24 SM320000 Up arrow 
25 $M330000 Down arrow 
26 SM310000 Right arrow 
27 SM300000 Left arrow 
28 SA420000 Right angle symbol 
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GCGID 
SM780000 
SM600000 
SV040000 
SP010000 
SP020000 
SP040000 
SM010000 
$C030000 
SM020000 
SM030000 
SP050000 
SP060000 
SP070000 
SM040000 
SA010000 
SP080000 
SP100000 
SP110000 
SP120000 
ND100000 
NDO10000 
NDO20000 
ND0O30000 
ND0O40000 
NDO50000 
NDO60000 
NDO70000 
NDO80000 
NDOg90000 
SP130000 
SP140000 
SA030000 
SA040000 
SA050000 
SP150000 
SM050000 
LA020000 
LB020000 
LC020000 
LD020000 
LE020000 
LFO20000 
LG020000 
LH020000 
LI020000 
LJO020000 
LKO20000 
LLO20000 
LM020000 
LNO20000 
LO020000 
LP020000 
LQ020000 


Description 

Left-right arrow 

Solid triangle 

Solid triangle, inverted 


Space 


Exclamation point 
Quotation marks 
Number sign 


Dollar sign 


Percent sign 


Ampersand 
Apostrophe 


Left parenthesis 
Right parenthesis 


Asterisk 
Plus sign 
Comma 


Hyphen/minus sign 
Period/full stop 


Slash 
zero 
One 
Two 
Three 
Four 
Five 
Six 
Seven 
Eight 
Nine 
Colon 
Semicolon 


Less than sign/greater than (arabic) 


Equal Sign 


Greater than sign/less than (arabic) 
Question mark 


At sign 

A capital 
B capital 
C capital 
D capital 
E capital 
F capital 
G capital 
H capital 
| capital 

J capital 
K capital 
L capital 
M capital 
N capital 
O capital 
P capital 
Q capital 
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120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 


GCGID 
LR020000 
LS020000 
LT020000 
LU020000 
Lv020000 
LWw020000 
LXx020000 
LY020000 
LZ020000 
SM060000 
SM070000 
SM080000 
SD150000 
SP090000 
$D130000 
LA010000 
LBO10000 
LC010000 
LD010000 
LE010000 
LFO10000 
LG010000 
LH010000 
L1010000 
LJo10000 
LK010000 
LLO10000 
LMO010000 
LNO10000 
LO010000 
LP010000 
LQ010000 
LRO10000 
LS010000 
LT010000 
LU010000 
LV010000 
LWw010000 
LX010000 
LY010000 
LZ010000 
SM110000 
SM130000 
SM140000 
$D190000 
SM790000 
LC420000 
LU170000 
LE110000 
LA150000 
LA170000 
LA130000 
LA270000 


Description 

R capital 

S capital 

T capital 

U capital 

V capital 

W capital 

X capital 

Y capital 

Z capital 

Left bracket 
Backslash 

Right bracket 
Circumflex Accent 
Underline, continuous underscore 
Grave accent 

a small 

b small 

c small 

d small 

e small 

f small 

g small 

h small 

i small 

j small 

k small 

| small 

m small 

n small 

oO small 

p small 

q small 

r small 

s small 

t small 

u small 

v small 

w small 

Xx small 

y small 

z small 

Left brace 
Vertical line, logical OR 
Right brace 

Tilde 

House 

C cedilla capital 
U diaeresis small 
E acute small 

A circumflex small 
A diaeresis small 
A grave small 

A overcircle small 
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UGL 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 


GCGID 
LC410000 
LE150000 
LE170000 
LE130000 
LI170000 
LI150000 
LI130000 
LA180000 
LA280000 
LE120000 
LA510000 
LA520000 
LO150000 
LO170000 
LO130000 
LU150000 


LU130000 © 


LY170000 
LO180000 
LU180000 
LO610000 
$C020000 
LO620000 
SA070000 
$C070000 
LA110000 
L1110000 
LO110000 
LU110000 
LN190000 
LN200000 
SM210000 
SM200000 
SP160000 
SM530000 
SM660000 
NF0O10000 
NF040000 
SP030000 
SP170000 
SP180000 
SF140000 
SF150000 
SF160000 
SF110000 
SF090000 
LA120000 
LA160000 
LA140000 
SM520000 
SF230000 
SF240000 
SF250000 


Description 

C cedilla small 

E circumflex small 
E diaeresis small 

E grave small 

| diaeresis small 

| circumflex small 

1 grave small 

A diaeresis capital 
A overcircle capital 
E acute capital 

AE diphthong small 
AE diphthong capital 
O circumflex small 
O diaeresis small 
O grave small 

U circumflex small 
U grave small 

Y diaeresis small 
O diaeresis capital 
U diaeresis capital 
O slash small 
Pound sterling sign 
O slash capital 
Multiply sign 

Florin sign 

A acute small 


| acute small 


O acute small 

U acute small 

N tilde smail 

N tilde capital 

Ordinal indicator, feminine 
Ordinal indicator, masculine 
Question mark, inverted 
Registered trademark symbol 
Logical NOT, end of line symbol 
One-half 

One-quarter 

Exclamation point, inverted 
Left angled quotes 

Right angled quotes 

Fill character, light 

Fill character, medium 

Fill character, heavy 

Center box bar vertical 

Right middle box side 

A acute capital 

A circumflex capital 

A grave capital 

Copyright symbol 

Right box side double 

Center box bar vertical double 


' Upper right box corner doubie 
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UGL 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 
224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
240 


GCGID 
SF260000 
$C040000 
$C050000 
SF030000 
SF020000 
SF070000 
SFO60000 
SF080000 
SF100000 
SF050000 
LA190000 
LA200000 
SF380000 
SF390000 
SF400000 
SF410000 
SF420000 
SF430000 
SF440000 
$C010000 
LD630000 
LD620000 
LE160000 
LE180000 
LE140000 
LI610000 
L1120000 
LI160000 
LI180000 
SF040000 
SF010000 
SF610000 
SF570000 
SM650000 
L1140000 
SF600000 
LO120000 
LS610000 
LO160000 
LO140000 
LO190000 
LO200000 
SM170000 
LT630000 
LT640000 
LU120000 
LU160000 


LU140000 _ 


LY110000 
LY120000 
SM150000 
$D110000 
SP320000 


Description 

Lower right box corner double 
Cent sign 

Yen sign 

Upper right box corner 
Lower left box corner 

Middle box bottom 

Middle box top 

Left middle box side 

Center box bar horizontal 
Box intersection 

A tilde small 

A tilde capital 

Lower left box corner double 
Upper left box corner double 
Middle box bottom double 
Middle box top double 

Left box side double 

Center box bar horizontal double 
Box intersection double 
International currency symbol 
eth Icelandic small 

D stroke capital, Eth Icelandic capital 
E circumflex capital 

E diaeresis capital 

E grave capital 

! dotless small 

| acute capital 

1 circumflex capital 

| diaeresis capital 

Lower right box corner 
Upper left box corner 

Solid fill character 

Solid fill character, bottom half 
Vertical line, broken 

| grave capital 

Solid fill character, top half 
O acute capital 

Sharp s small 

O circumflex capital 

O grave capital 

O tilde small 

O tilde capital 

Micro symbol 

Thorn Icelandic small 

Thorn Icelandic capital 

U acute capital 

U circumflex capital 

U grave capital 

y acute small 

Y acute capital 

Overline 

Acute accent 

Syllable hyphen 
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UGL 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 
254 
255 
256 
257 
258 
259 
260 
261 
262 
263 
264 
265 
266 
267 
268 
269 
270 
271 
272 
273 
274 
275 
276 
277 
278 
279 
280 
281 
282 
283 
284 
285 
286 
287 
288 
289 
290 
291 
292 
293 


GCGID 
$A020000 
SM100000 
NF050000 
SM250000 
SM240000 
SA060000 
$D410000 
SM190000 
$D170000 
SD630000 
NDO11000 
ND031000 
ND021000 
SM470000 
SP300000 
SC060000 
SM680000 
SF190000 
SF200000 
SF210000 
SF220000 
SF270000 
SF280000 
SF360000 
SF370000 
SF450000 
SF460000 
SF470000 
SF480000 
SF490000 
SF500000 
SF510000 
SF520000 
SF530000 
SF540000 
SF580000 
SF590000 
GA010000 
GGo20000 
GP010000 
Gso020000 
GS010000 
GT010000 


GF020000 . 


GT620000 
GO320000 
GD010000 
SA450000 
GF010000 
GE010000 
SA380000 
SA480000 
SA530000 


Description 

Plus or minus sign 

Double underscore 

Three-quarters 

Paragraph symbol (USA) 

Section symbol (USA), paragraph (Europe) 
Divide sign 

Cedilla (or sedila) accent 

Degree symbol 

Diaeresis, umlaut accent 

Middle dot 

One superscript 

Three superscript 

Two superscript 

Solid square, histogram, square bullet 
Required space 

Peseta sign 

Start of line symbol 

Right box side double to single 

Right box side single to double 

Upper right box corner single to double 
Upper right box corner double to single 
Lower right box corner single to double 
Lower right box corner double to single 
Left box side single to double 

Left box side double to single 

Middle box bottom single to double 
Middle box bottom double to single 
Middle box top double to single 
Middle box top single to double 
Lower left box corner double to single 
Lower left box corner single to double 
Upper left box corner single to double 
Upper left box corner double to single 
Box intersection single to double 

Box intersection double to single 
Solid fill character, left haif 

Solid fill character, right half 

Alpha small 

Gamma capital 

Pi small 

Sigma capital 

Sigma small 

Tau small 

Phi capital 

Theta capital 

Omega capital 

Delta small 

Infinity symbol 

Phi small 

Epsilon small 

Intersection, logical product 

Indentity symbol, almost equal 
Greater than or equal sign 
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UGL 
294 
295 
296 
297 
298 
299 
300 
301 
302 
303 
304 
305 
306 
307 
308 
309 
310 
311 
312 
313 
314 
315 
316 
317 
318 
319 
320 
321 
322 
323 
324 
325 
326 
327 
328 
329 
330 
331 
332 
333 
334 
335 
336 
337 
338 
339 

— 340 
341 
342 
343 
344 
345 
346 


GCGID 
$SA520000 
$S260000 
$S270000 
SA700000 
SA790000 
SA800000 
LNO1 1000 
$D310000 
$D230000 
SD290000 
$D270000 
$D250000 
$D430000 
$D210000 
SP190000 
SP200000 
SP210000 
SP220000 
$S680000 
SM900000 
$D150000 
$D190000 
SP260000 
SP230000 
$V520000 
SM340000 
SM350000 
$D150100 
SM560000 
LS220000 
SP270000 
LO520000 
$D190100 
SM540000 
LS210000 
SP280000 
LO510000 
LY180000 
LG230000 
LG240000 
LI300000 
LS410000 
LS420000 
LA230000 
LA240000 
LA430000 
LA440000 
LC110000 
LC120000 
LC210000 
LC220000 


‘LD210000 


LD220000 


Description 

Less than or equal sign 
Upper integral symbol section 
Lower integral symbol section 
Nearly equals symbol 
Product dot 

Radical symbol 

N small superscript 

Macron accent 

Breve accent 

Overdot accent (over small Alpha) 
Overcircle accent 

Double acute accent 

Ogonek accent 

Caron accent 

Left single quote 

Right single quote 

Left double quotes 

Right double quotes 

Endash 

Emdash 

Circumflex accent 

Tilde accent 

Single quote on baseline (German lower) 
Left lower double quotes 
Ellipsis 
Dagger footnote indicator 
Double dagger footnote indicator 
Circumflex accent (over small alpha) 
Permille symbol 

S caron capital 

French single open quote 

OE ligature capital 

Tilde accent (over smail alpha) 
Trademark symbol! 

S caron small 

French single close quote 

oe ligature small 

Y diaeresis capital 

g Breve Small 

G Breve Capital 

| Overdot Capital 

s Cedilla Small 

S Cedilla Capital 

a Breve Small 

A Breve Capital 

a Ogonek Smail 

A Ogonek Capital 

c Acute Small 

C Acute Capital 

c Caron Small 

C Caron Capital 

d Caron Small 

D Caron Capital 
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UGL 
347 
348 
349 
350 
351 
352 
353 
354 
355 
356 
357 
358 
359 
360 
361 
362 
363 
364 
365 
366 
367 
368 
369 
370 
371 
372 
373 
374 
375 
376 
377 
378 
379 
380 
381 
382 
383 


GCGID 

LD610000 
LE210000 
LE220000 
LE430000 
LE440000 
LL110000 
LL120000 
LL210000 
LL220000 
LL610000 
LL620000 
LN110000 
LN120000 
LN210000 
LN220000 
LO250000 
LO260000 
LR110000 
LR120000 
LR210000 
LR220000 
LS110000 
LS120000 
LT210000 
LT220000 
LT410000 
LT420000 
LU250000 
LU260000 
LU270000 
LU280000 
LZ110000 
LZ120000 
LZ210000 
LZ220000 
LZ290000 
LZ300000 


Description 

d Stroke Small 

e Caron Small 

E Caron Capital 

e Ogenek Small 

E Ogonek Capital 

| Acute Small 

L Acute Capital 

| Caron Small 

L Caron Capital 

| Stroke Small 

L Stroke Capital 

n Acute Small 

N Acute Capital 

n Caron Small 

N Caron Capital 

o Double Acute Smal! 
O Double Acute Capital 
r Acute Smail 

R Acute Capital 

r Caron Small 

R Caron Capital 

s Acute Small 

S Acute Capital 

t Caron Small 

T Caron Capital 

t Cedilla Small 

T Cedilla Capital 

u Double Acute Small 
U Double Acute Capital 
u Overcircle Small 

u Overcircle Capital 
z Acute Small 

Z Acute Capital 

z Caron Small 


~ Z Caron Capital 


z Overdot Small 
Z Overdot Capital 
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aos Guan’ Ieee 7 
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Figure 32-2. US-English: ASCII Code Page 437 
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Selel—lelc ae 
a) 
ACACHREERE Glw 
8 |-8 [it (|8 |H|x 
ip | ea 
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I2-C/ei_|.f<fLi vii | 
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Figure 32-3. Latin 1 Multilingual: ASCII Code Page 850 
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= 
a 
wt 
a 
S 
N 
aq 
= 
eo 
= 
iS 
i: 
= 
ret 
= 
= 
= 
& oe ne} oO; Ge en; & ae wd oie ee 
| un sod cad can ca cae aca ae 
S| + © aad w lol m+ [>| “A lz1e 
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T 
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eae Sela eee 


Figure 32-4, Latin 2 Multilingual: ASCII Code Page 852 
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| O | 16 | 32 | 48 | 64! 80 | 96 |112] |128| 144] 160|176 | 192|208 | 224 | 240 
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TSE eel ele eis ea ae 


Figure 32-5. Turkey: ASCII Code Page 857 
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a_i 


IF 


1 REI 


| 


eS 


: 


12| |128|144|160|176|192|208/|224|240 


. Co a lowed Cc a a Cc 
oO 


ian | 

Siu n l 

z O| 

alt te if iF [ | 7 

m —| = |] ALR] Blew |weiajy*] + «| 1 . al 
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er [SPO] Fo ees SS a S| 4 


Figure 32-6. Portuguese: ASCII Code Page 860 
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4/240 
E-|F 
a 
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re 
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+R 


I 
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0 | 16 | 32 | 48 | 64 | 80 | 96 |112| | 
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—|) ti) dt 
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20 | | </ 3/9] 4/ ma 
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Figure 32-7. Iceland: ASCII Code Page 861 
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Figure 32-8. Canadian-French: ASCIIl Code Page 863 
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Figure 32-9. Norwegian: ASCII Code Page 865 
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it 
FP 
& 


D 
E 
F 
G 
H 


Figure 32-10. Desktop Publishing: ASCII Code Page 1004 
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Figure 32-11. US-English: EBCDIC Code Page 037 
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Figure 32-12. Austrian/German: EBCDIC Code Page 273 
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Figure 32-13. Belgian: EBCDIC Code Page 274 (supported for migration purposes) 
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Figure 32-14. Danish/Norwegian: EBCDIC Code Page 277 
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Figure 32-15. Finnish/Swedish: EBCDIC Code Page 278 


Chapter 32. Code Pages 32-25 


|g Orn 4 8 67) 89 ABC Doe 
0 | | ee Oe 
j/72l#lAld 1 


-1 ] ? 

2] | | | fete els [elie] x]s [2 

3 | | | ete ley felzl ais 
Pete ed . 


Figure 32-16. Italian: EBCDIC Code Page 280 
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Figure 32-17. Portuguese: EBCDIC Code Page 282 (supported for migration purposes) 
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Figure 32-18. Spanish: EBCDIC Code Page 284 
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Figure 32-19. UK-English: EBCDIC Code Page 285 
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Figure 32-20. French: EBCDIC Code Page 297 
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Figure 32-21. International: EBCDIC Code Page 500 
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Figure 32-22. Czechoslovakia/Hungary/Poland/Yugoslovia: EBCDIC Code Page 870 
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Figure 32-23. Iceland: EBCDIC Code Page 871 
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Figure 32-24, Turkey: EBCDIC Code Page 1026 . 
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Appendix A. Data Types 


The following data types are used in Presentation Manager. They are listed in alphabetic 
order. 


ACCEL 


Accelerator structure. 


Syntax 


“typedef struct ACCEL { _ 
- USHORT ole 
key; 


eo omdy 


Fields 
fs (USHORT) 
Options. 


key (USHORT) 
Key. 

cmd (USHORT) 
Command code. 


The value to be placed in the uscmd parameter of a WM_HELP, a WM_COMMAND, or 
a WM_SYSCOMMAND. 


ACCELTABLE 


Accelerator-table structure. 


Syntax 


© Copyright IBM Corp. 1994 . A-1 


Fields 
cAccel (USHORT) 


Number of accelerator entries. 


codepage (USHORT) 


Code page for accelerator entries. 


aaccel[1] (ACCEL) 
Accelerator entries. 


The default accelerator table has the following 16 entries: 


Options 


HELP 

SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND ALT 
SYSCOMMAND 
SYSCOMMAND LONEKEY 
SYSCOMMAND LONEKEY 
SYSCOMMAND ALT 
SYSCOMMAND SHIFT 
SYSCOMMAND CONTROL 


APIRET 


VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 
VIRTUALKEY 


Key 


VK_F1 
VK_F4 
VK_ENTER 
VK_NEWLINE 
VK_F5 
VK_F6 
VK_F7 
VK_F8 
VK_F9 
VK_F10 
VK_F10 
VK_ALT 
VK_ALTGRAF 
VK_SPACE 
VK_ESC 
VK_ESC 


Command 


0 
SC_CLOSE 
SC_RESTORE 
SC_RESTORE 
SC_RESTORE 
SC_NEXTFRAME 
SC_MOVE 
SC_SIZE 
SC_MINIMIZE 
SC_MAXIMIZE 
SC_APPMENU 
SC_APPMENU 
SC_APPMENU 
SC_SYSMENU 
SC_SYSMENU 
SC_TASKMANAGER 


Unsigned integer in the range 0 through 4 294 967 295. 


Syntax 


APSZ 


An array of pointers to NULL-terminated strings. 


Syntax 
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ARCPARAMS 


Arc-parameters structure. 


Syntax 


typedef struct _ARCPARAMS { 
LONG TP; oe 
LONG 1Q; 

LONG = TR; 
‘LONG TS; 

} ARCPARAMS; 


typedef ARCPARAMS *PARCPARAMS; 


Fields 
IP (LONG) 
P coefficient. 


IQ (LONG) 
Q coefficient. 


IR (LONG) 
R coefficient. 


IS (LONG) 
S coefficient. 


AREABUNDLE 
Area-attributes bundle structure. 


Syntax 


- typedef struct _AREABUNDL 
: oo plore 
- WBackColor; 


__usBackMixMode 
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Fields 
IColor (LONG) . 
Area foreground color. 


IBackColor (LONG) 
Area background color. 


usMixMode (USHORT) 
Area foreground-mix mode. 


usBackMixMode (USHORT) 
Area background-mix mode. 


usSet (USHORT) 
Pattern set. 


usSymbol (USHORT) 
Pattern symbol. 


ptlRefPoint (POINTL) 
Pattern reference point. 


ATOM 
_ Atom identity. 


Syntax 


BITMAPARRAYFILEHEADER 


Bit-map array file header structure. 


Syntax 
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Fields 
usType (USHORT) 
Type of structure. 


Possible values are shown in the following list: 


BFT_BITMAPARRAY = (0x4142 - ‘BA’ for BSTMAPARRAYFILEHEADER or 
BITMAPARRAYFILEHEADER2) 


cbSize (ULONG) 
Size of the BPTMAPARRAYFILEHEADER structure in bytes. 


offNext (ULONG) 
Offset of the next BITMAPARRAYFILEHEADER structure from the start of the file. 


cxDisplay (USHORT) 
Device width, in pels. 


cyDisplay (USHORT) 
Device height, in pels. 


bfh (BITMAPFILEHEADER) 
Bit-map file header structure. 


BITMAPARRAYFILEHEADER2 


Bit-map array file header structure. 


Syntax 


BITMAPARRAYPILEHEADERZ {0 
Sie, 
= OTTNEXt; 
CXDISHIAYs) 


_eyDisplay: = 
Phe, 


Fields 
usType (USHORT) 
Type of structure. 


Possible values are shown in the following list: 


BFT_BITMAPARRAY  (0x4142. = ‘BA’ for BITMAPARRAYFILEHEADER or 
BITMAPARRAYFILEHEADER2) 
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cbSize (ULONG) f. 
Size of the BTTDMAPARRAYFILEHEADER2 structure in bytes. 


offNext (ULONG) 
Offset of the next BISTMAPARRAYFILEHEADER2 structure from the start of the file. 


cxDisplay (USHORT) 
Device width, in pels. 


cyDisplay (USHORT) 
Device height, in pels. 


bfh2 (BITMAPFILEHEADER2) 
Bit-map file header structure. 


BITMAPFILEHEADER 


Bit-map file header strcuture. 


Syntax 


Fields 
usType (USHORT) 
Type of resource the file contains. 


Possible values are shown in the following list: 


BFT_ BMAP | (0x4D42 - ‘BM’ for bitmaps) 
BFT_ICON .  (0x4349 - ‘IC’ for icons) 
BFT_POINTER (0x4540 - ‘PT’ for pointers) 
BFT_COLORICON (0x4943 - ‘Cl’ for color icons) 


BFT_COLORPOINTER  (0x5043 - ‘CP’ for color pointers) 


cbSize (ULONG) 
Size of the BITMAPFILEHEADER structure in bytes. 
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xHotspot (SHORT) 
Width of hotspot for icons and pointers. 


This field is ignored for bit maps. 


yHotspot (SHORT) 
Height of hotspot for icons and pointers. 


This field is ignored for bit maps. 


offBits (USHORT) 
Offset in bytes. 


Offset in bytes to beginning of bit-map pel data in the file, from the start of the definition. 


bmp (BITMAPINFOHEADER) 
Bit-map information header structure. 


BITMAPFILEHEADER2 


Bit-map file header structure. 


Syntax 


typedef struct _BITMAPFILEHEADER2 { 
USHORT - ustypes 
cbSize;. 
: xHotspot; 
yHotspot; 
A  SoffBits; 
. TMAPINFOHEADER2- _ bmp2; oO 
ea BITMAPE TLEHEADER2; 


_typeder | BLTHAPFILEHEADER2 ‘=POTTWAPFILENEADER2s 


Fields 
usType (USHORT) 
Type of resource the file contains. 


Possible values are shown in the following list: 


BFT_BMAP (0x4D42 - ‘BM’ for bitmaps) 
BFT_ICON (0x4349 - ‘IC’ for icons) 
BFT_POINTER (0x4540 - ‘PT’ for pointers) 
BFT_COLORICON (0x4943 - ‘Cl’ for color icons) 


BFT_COLORPOINTER (0x5043 - ‘CP’ for color pointers) 


cbSize (ULONG) 
Size of the BITMAPFILEHEADER2 structure in bytes. 
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xHotspot (SHORT) 
Width of hotspot for icons and pointers. 


This field is ignored for bit maps. 


yHotspot (SHORT) 
Height of hotspot for icons and pointers. 


This field is ignored for bit maps. 


offBits (USHORT) 
Offset in bytes. 


. Offset in bytes to beginning of bit-map pel data in the file, from the start of the definition. 


bmp2 (BITMAPINFOHEADER2) 
Bit-map information header structure. 


BITMAPINFO 


Bit-map information structure. 


Each bit plane logically contains (cx * cy * cBitCount) bits, although the actual length can be 
greater because of padding. 


See also “BITMAPINFO2” on page A-9, which is preferred. 


Syntax 


Fields 
cbFix (ULONG) 
Length of fixed portion of structure. 


This length can be determined using sizeof (BITMAPINFOHEADER). 


cx (USHORT) 
Bit-map width in pels. 
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cy (USHORT) 
Bit-map height in pels. 


cPlanes (USHORT) 
Number of bit planes. 


cBitCount (USHORT) 
Number of bits per pel within a plane. 


argbColor[1] (RGB) 
Array of RGB values. 


This is a packed array of 24-bit RGB values. If there are N bits per pel (N = cPlanes * 
cBitCount), the array contains 2**N RGB values. However, if N = 24, the bit map does 
not need the color color array because the standard-format bit map, with 24 bits per pel, 
is assumed to contain RGB values. 


BITMAPINFO2 


Bit-map information structure. 


Each bit plane logically contains (cx * cy * cBitCount) bits, although the actual length can be 
greater because of padding. 


Note: Many functions can accept either this structure or the BITMAPINFO structure. Where 
possible, BITMAPINFO2 should be used. 


The cbFix field is used to find the color table, if any, that goes with the information in this 
structure. A color table is an array of color (RGB2) values. If there are N bits per pel 

(N = cPlanes * cBitCount), the array contains 2**N color values. However, if N = 24, the 
color table is not required (because the standard-format bit map, with 24 bits per pel, is 
assumed to contain RGB values), unless either cc/rUsed or ccirlmportant is non-zero. 
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__ecirimporta 

usUnits; 

~ usReserved; 
-usRecording; — 
__usRendering; — 
POST ARN ei 


INFOQ =PBITMAPINO2s =” 


Fields 
cbFix (ULONG) | 
Length of fixed portion of structure. 


The structure can be truncated after cBitCount or any subsequent field. 


The length does not include the length of the color table. Where the color table is 
present, it is at an offset of cbFix from the start of the BITMAPINFO2 structure. 


This length can range from 16 (BITMAPINFOHEADER through field cBitCount) up to 
sizeof (BITMAPINFOHEADER2) bytes. 


cx (ULONG) 
Bit-map width in pels. 


cy (ULONG) 
Bit-map height in pels. 


cPlanes (USHORT) 
Number of bit planes. 


cBitCount (USHORT) 
Number of bits per pel within a plane. 


ulCompression (ULONG) 
Compression scheme used to store the bit map. — 
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BCA_UNCOMP 
Bit map is uncompressed. 


BCA_HUFFMAN1D 
The bit map is compressed by a modified Huffman encoding. This is valid for a 
bi-level (one bit per pel) bit map. 


BCA_RLE4 
The bit map is a 4-bit per pel run-length encoded bit map. See the following section, 
“Format of Compressed Data,” for a description of the format of the compressed 
data. 


BCA_RLE8 
The bit map is an 8-bit per pel run-length encoded bit map. See the following 
section, “Format of Compressed Data,” for a description of the format of the 
compressed data. 


BCA_RLE24 
The bit map is a 24-bit per pel run-length encoded bit map. See the following 
section, “Format of Compressed Data,” for a description of the format of the 
compressed data. 


Format of Compressed Data 
Encoding a run length: 


Run-length encoded bit maps are encoded in the buffer in a controlled format. In all 
cases, if the first byte is non-zero, it is the length of a run of pels of a particular color or, 
in the case of a BCA_RLE4 bit map, a run of a length of pels of alternating colors. 


Ist-byte pel repetition count >= 1 
2nd-4th bytes (BCA_RLE24 only) RGB value of pel. 
2nd-byte (BCA_RLE8) color index of pel to be repeated 


(BCA_RLE4) the second byte contains 2 4-bit 
color indexes. The repetition count is 
completed by alternately choosing the high-order 
nibble followed by the low-order nibble for the 
succeeding pels until the count is exhausted. 


Unencoded run: 
An unencoded run is a string of pels to be placed in consecutive positions in the 
destination bit map. 


lst-byte 0 
2nd-byte COUNT = a multiple of 3 for BCA_RLE24 bit maps, or 
COUNT >= 3 (for BCA_RLE4 and BCA_RLE8 bit maps). 
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followed by the bytes as follows: 


BCA_RLE24 . 
- A string of bytes specifying the RGB color values of succeeding pels. If COUNT is 
odd, it must be padded by a zero byte for an even length overall. 


BCA_RLE8 
A string of bytes specifying color indexes for succeeding pels. If COUNT is odd, it 
must be padded by a zero byte for an even length overall. 


BCA_RLE4 
A string of bytes, each byte providing two color indexes, with the high-order nibble 
specifying the index of the pel preceding the low-order nibble. The COUNT specifies 
the number of indexes. The overall length of the string must be an even number of 
bytes, and thus may be padded with a Zero byte, and the low order nibble of the last 
significant byte may also be zero and not used. 


Delta record: 


A delta record indicates a shift in position in the destination bit map before the next 
record is decoded. 


Ist-byte 0 
2nd-byte 2 
3rd-byte Delta-x (unsigned) 
4th-byte Delta-y (unsigned) 


This is a relative jump record. It implies that the next record is to be decoded into a 
position in the destination bit map at an offset from the current position, determined by 
changing the horizontal and vertical positions by Delta-x and Delta-y, respectively. 


End-of-line record: The end-of-line record signifies that the data for the current scan 
line is complete and that decoding of the next record should begin at the start of the 
next scan line. 


Ist-byte 0 
2nd-byte 0 


End-of-RLE record: 


The end-of-RLE record signifies the end of the data in the RLE compressed bit map. 


Ist-byte 0 
2nd-byte 1 


cblmage (ULONG) 
Length of bit-map storage data, in bytes. 


If the bit map is uncompressed, zero (default) can be specified for this. — 


cxResolution (ULONG) 
Horizontal component of the resolution of target device. 


The resolution of the device the bit map is intended for, in the units specified by usUnits. 
This information enables an application to select from a resource group the bit map that 
best matches the characteristics of the current output device. 
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cyResolution (ULONG) 
Vertical component of the resolution of the target device. 


See the description of cxResolution. 


cclrUsed (ULONG) 
Number of color indexes used. 


‘The number of color indexes from the color table that are used by the bit map. If it is 
zero (the default), all the indexes are used. If it is non-zero, only the first ccirUsed 
entries in the table are accessed by the system, and further entries can be omitted. 


For the standard formats with a cBitCount of 1, 4, or 8 (and cPlanes equal to 1), any 
indexes beyond ccirUsed are not valid. For example, a bit map with 64 colors can use 
the 8-bitcount format without having to supply the other 192 entries in the color table. 
For the 24-bitcount standard format, ccirUsed is the number of colors used by the bit 
map. 


cclrimportant (ULONG) 
Minimum number of color indexes for satisfactory appearance of the bit map. 


More colors may be used in the bit map, but it is not necessary to assign them to the 
device palette. These additional colors may be mapped to the nearest colors available. 


Zero (the default) means that all entries are important. 


For a 24-bitcount standard format bit map, the cc/rimportant colors are also listed in the 
color table following the BITMAPINFO2 structure. 


usUnits (USHORT) 
Units of measure. 


Units of measure of the horizontal and vertical components of resolution, cxResolution 
and cyResolution. 


BRU_METRIC Pels per meter. This is the default value. 


usReserved (USHORT) 
Reserved. 


This is a reserved field. 


usRecording (USHORT) 
Recording algorithm. 


The format in which the bit map data is recorded. 


BRA_BOTTOMUP _ Scan lines are recorded bottom to top. This is the default value. 
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usRendering (USHORT) 
Halftoning algorithm. 


The algorithm used to record bit map data that has been digitally halftoned. 


BRH_NOTHALFTONED Bit-map data is not halftoned. This is the default value. 
BRH_ERRORDIFFUSION _ Error Diffusion or Damped Error Diffusion algorithm. 


BRH_PANDA Processing Algorithm for Non-coded Document Acquisition. 
BRH_SUPERCIRCLE Super Circle algorithm. 

cSize1 (ULONG) 
Size value 1. 


lf BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as 
a percentage in the range 0 through 100. A value of 100% indicates no damping, and a 
value of 0% indicates that any errors are not diffused. 


lf BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize7 is the x dimension of the 
pattern used, in pels. 


cSize2 (ULONG) 
Size value 2. 


lf BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored. 


If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the y dimension of the 
pattern used, in pels. 


ulColorEncoding (ULONG) 
Color encoding. 


BCE_RGB_~ Each element in the color array is an RGB2 datatype. This is the default 
value. 


ulldentifier (ULONG) 
Reserved for application use. 


argbColor[1] (RGB2) 
Array of RGB values. 


This is a packed array of 24-bit RGB values. If there are N bits per pel (N = cPlanes * 
cBitCount), the array contains 2**N RGB values. However, if N = 24, the bit map does 
not need the color array because the standard-format bit map, with 24 bits per pel, is 
assumed to contain RGB values. 


BITMAPINFOHEADER 
Bit-map information header structure. 


Each bit plane logically contains (cx * cy * cBitCount) bits, although the actual length can be 
greater because of padding. 


See also BITMAPINFOHEADER2, which is preferred. 
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Syntax 


‘ypedet Stnuet. _BITWAPTNFOHEAD 
ULONG. cbFix; = 
USHORT “CX$ 
_USHORT —s_scy; 

USHORT —=—s cPlanes; - 

USHORT cBitCount; 
3 BITMAPINFOHEADER; ; 


fret BITMAPINFOHEADER +PBITHAPINFOHEADER; 


Fields 
cbFix (ULONG) 
Length of structure. 


cx (USHORT) 
Bit-map width in pels. 


cy (USHORT) 
Bit-map height in pels. 


cPlanes (USHORT) 
Number of bit planes. 


cBitCount (USHORT) 
Number of bits per pel within a plane. 


BITMAPINFOHEADER2 


Bit-map information header structure. 


Each bit plane logically contains (cx * cy * cBitCount) bits, although the actual length can be 
greater because of padding. 


Note: Many functions can accept either this structure or the BITMAPINFOHEADER 
structure. Where possible, use BITMAPINFOHEADERZ2. 
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Syntax 


_cclrImportan 
= usUnits; 
_usReserved; 
usRecording; 

- usRendering; 


WAPINFOHEADER2; = 


Fields 
cbFix (ULONG) 
Length of structure. 


The structure can be truncated after cBitCount or any subsequent field. 


cx (ULONG) 
Bit-map width in pels. 


cy (ULONG) 
Bit-map height in pels. 


cPlanes (USHORT) 
Number of bit planes. 


cBitCount (USHORT) 
Number of bits per pel within a plane. 


ulCompression (ULONG) 
Compression scheme used to store the bit map. 


BCA_UNCOMP 
Bit map is uncompressed. 


BCA_HUFFMAN1D | | 
The bit map is compressed by a modified Huffman encoding. This is valid for a 
bi-level (one bit per pel) bit map. 
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BCA_RLE4 
The bit map is a 4-bit per pel run-length encoded bit map. See the following section, 
“Format of Compressed Data,” for a description of the format of the compressed 
data. 


BCA_RLE8 
The bit map is an 8-bit per pel run-length encoded bit map. See the following 
section, “Format of Compressed Data,” for a description of the format of the 
compressed data. 


BCA_RLE24 
The bit map is a 24-bit per pel run-length encoded bit map. See the following 
section, “Format of Compressed Data,” for a description of the format of the 
compressed data. 


Format of Compressed Data 
Encoding a run length: 


Run length encoded bit maps are encoded in the buffer in a controlled format. In all 
cases, if the first byte is non-zero, it is the length of a run of pels of a particular color or, 
in the case of a BCA_RLE4 bit map, a run of a length of pels of alternating colors. 


ist-byte pel repetition count >= 1 
2nd-4th bytes (BCA_RLE24 only) RGB value of pel. 
2nd-byte (BCA_RLE8) color index of pel to be repeated 


(BCA_RLE4) the second byte contains 2 4-bit 
color indexes. The repetition count is 
completed by alternately choosing the high-order 
nibble followed by the low-order nibble for the 
succeeding pels until the count is exhausted. 


Unencoded run: 


An unencoded run is a string of pels to be placed in consecutive positions in the 
destination bit map. 
lst-byte 0 


2nd-byte COUNT = a multiple of 3 for BCA_RLE24 bit maps, or 
COUNT >= 3 (for BCA_RLE4 and BCA_RLE8 bit maps). 


followed by the bytes as follows: 


BCA_RLE24 
A string of bytes specifying the RGB color values of succeeding pels. If COUNT is 
odd, it must be padded by a zero byte for an even length overall. 


BCA_RLE8 
A string of bytes specifying color indexes for succeeding pels. If COUNT is odd, it 
must be padded by a zero byte for an even length overall. 


BCA_RLE4 
A string of bytes, each byte providing two color indexes, with the high-order nibble 
specifying the index of the pel preceding the low-order nibble. The COUNT specifies 
the number of indexes. The overall length of the string must be an even number of 
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bytes, and thus may be padded with a zero byte, and the low order nibble of the last 
significant byte may also be zero and not used. 


Delta record: 


A delta record indicates a shift in position in the destination bit map before the next 
record is decoded. 


Ist-byte 0 
2nd-byte 2 
3rd-byte Delta-x (unsigned) 
4th-byte Delta-y (unsigned) 


This is a relative jump record. It implies that the next record is to be decoded into a 
position in the destination bit map at an offset from the current position, determined by 
changing the horizontal and vertical positions by Delta-x and Delta-y, respectively. 


End-of-line record: 


The end-of-line record signifies that the data for the current scan line is complete and 
that decoding of the next record should begin at the start of the next scan line. 


1st-byte 0 
2nd-byte 0 


End-of-RLE record: 


The end-of-RLE record signifies the end of the data in the RLE compressed bit map. 


Ist-byte 0 
2nd-byte ] 


cbimage (ULONG) 
Length of bit-map storage data, in bytes. 


If the bit map is uncompressed, zero (the default) can be specified for this. 


cxResolution (ULONG) 
Horizontal component of the resolution of target device. 


The resolution of the device the bit map is intended for, in the units specified by usUnits. 
This information enables applications to select from a resource group the bit map that 
best matches the characteristics of the current output device. 


cyResolution (ULONG) 
Vertical component of the resolution of target device. 


See the description of cxResolution. 


cclrUsed (ULONG) 
Number of color indexes deed, 


The number of color indexes from the color table that are used by the bit map. If this is 
zero (the default), all the indexes are used. [f it is non-zero, only the first cclrused 
entries in the table are accessed by the system, and further entries can be omitted. 


For the standard formats with a cBitCount of 1, 4, or 8 (and cPlanes equal to 1), any 
indexes beyond ccirUsed are invalid. For example, a bit map with 64 colors can use the 
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8-bitcount format without having to supply the other 192 entries in the color table. For 
the 24-bitcount standard format, ccirUsed is the number of colors used by the bit map. 


cclrimportant (ULONG) 
Minimum number of color indexes for satisfactory appearance of the bit map. 


More colors may be used in the bit map, but it is not necessary to assign them to the 
device palette. These additional colors may be mapped to the nearest colors available. 


Zero (the default) means that all entries are important. 


For a 24-bitcount standard format bit map, the cc/rimportant colors are also listed in the 
color table relating to this bit map. 


usUnits (USHORT) 
Units of measure. 


Units of measure of the horizontal and vertical resolution, cxResolution and 
cyResolution. 


BRU_METRIC Pels per meter. This is the default value. 


usReserved (USHORT) 
Reserved. 


This is a reserved field. If present, it must be zero. 


usRecording (USHORT) 
Recording algorithm. 


The format in which the bit-map data is recorded. 
BRA_BOTTOMUP _ Scan lines are recorded bottom to top. This is the default value. 


usRendering (USHORT) 
Halftoning algorithm. 


The algorithm used to record bit-map data that has been digitally halftoned. 


BRH_NOTHALFTONED Bit-map data is not halftoned. This is the default value. 
BRH_ERRORDIFFUSION _ Error Diffusion or Damped Error Diffusion algorithm. 


BRH_PANDA Processing Algorithm for Non-coded Document Acquisition. 
BRH_SUPERCIRCLE Super Circle algorithm. 

cSize1 (ULONG) 
Size value 1. 


lf BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as 
a percentage in the range 0 through 100. A value of 100% indicates no damping, and a 
value of 0% indicates that any errors are not diffused. 


If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize7 is the x dimension of the 
pattern used, in pels. 


cSize2 (ULONG) 
Size value 2. 


lf BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored. 
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lf BRH_PANDA or BRH_SUPERCIRCLE is pet cSize2 is the y dimension of the 
pattern used, in pels. 


ulColorEncoding (ULONG) 
Color encoding. 


BCE_RGB Each element in the color array is an RGB2 datatype. This is the default 
value. 


ulldentifier (ULONG) 
Reserved for application use. 


BIT16 
Defines 16 independent BOOL values. 


Syntax 


BIT32 
Defines 32 independent BOOL values. 


Syntax 


BIT8 
Defines eight independent BOOL values. 


Syntax 
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BOOL 


Boolean. 


Valid values are FALSE, which is 0, and TRUE, which is 1. 


Syntax 


BOOKPAGEINFO 


Notebook page information structure. 


Syntax 


“typedet struct ~_BOOKPAGEINFO {, 
-ULONG © ee ae 
~ ULONG ee cone hls 
BOGE i ce —bLoadDlg; 
iene ulPageData; 
hwndPage; 

pfnPageDlgProc; 

idPageDlg; 

-- hmodPageDlg; | 
- pPageDlgCreateParam; 

— pdigtPage; — 
ee 


| HBITMAP 
—ULONG © 
PSZ 
sel 
PSZ 
-PVOID 
be ‘BOOKPAGEINFO: 


cer BOOKPAGEINFO 7 


Fields 
cb (ULONG) 
Size of the page information structure. 


fl (ULONG) 
Flag indicating which page attributes are 5 to be set. 


BFA_BIDIINFO Reserved for bi-directional support. 
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BFA_MAJORTABBITMAP Set/query major tab bit map. 


BFA_MAJORTABTEXT Set/query major tab text. 

BFA_MINORTABBITMAP Set/query minor tab bit map. 

BFA_MINORTABTEXT Set/query minor tab text. 

BFA_PAGEDATA Set/query page data. 

BFA_PAGEFROMDLGRES Set/query page window handle from a dialog 
resource. 

BFA_PAGEFROMDLGTEMPLATE _ Set/query page window handle from a dialog 
template. 

BFA_PAGEFROMHWND Set/query page window handle. 


BFA_STATUSLINE Set/query status text. 


bLoadDlig (BOOL) 
Load dialog flag. 


TRUE Load dialog immediately. 
FALSE Load dialog on page turn. 


ulPageData (ULONG) 
Data to associate with the notebook page. 


hwndPage (HWND) 
Handle to associate with the notebook page. 


pfnPageDligProc (PFN) 
Dialog procedure. 


idPageDig (ULONG) 
Dialog id. 


hmodPageDlig (HMODULE) 
Resource handle. 


pPageDigCreateParam (PVOID) 
Dialog create parameters. 


pdigtPage (PDLGTEMPLATE) 
Dialog template. 


cbStatusLine (ULONG) 
Length of status line text. 


pszStatusLine (PSZ) 
Status line text string. 


hbmMajorTab (HBITMAP) 
Major tab bit map handle. 


hbmMinorTab (HBITMAP) 
Minor tab bit map handle. 


cbMajorTab (ULONG) 
Length of major tab text. 
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pszMajorTab (PSZ) 
Major tab text string. 


cbMinorTab (ULONG) 
Length of minor tab text. 


- pszMinorTab (PSZ) 
Minor tab text string. 


pBidilnfo (PVOID) 
Reserved for bi-directional support. 


BOOKTEXT 
Notebook data structure that contains text strings for notebook status lines and tabs. This 
data structure is used with the BKM_QUERYSTATUSLINETEXT and the 
BKM_QUERYTABTEXT messages only. See “BKM_QUERYSTATUSLINETEXT” on 
page 23-18 and “BKM_QUERYTABTEXT” on page 23-20 for information about those 
messages. 


Syntax 


typedef struct _BOOKTEXT { 
‘PSZ “pString;. 
ULONG ..__textLen; : 
--} BOOKTEXT; ae 


typedef BOOKTEXT *PBOOKTEXT; 


Fields 
pString (PSZ) 
Pointer to a string buffer. 


Buffer in which the text string is to be placed. For the BKM_QUERYSTATUSLINETEXT 
message, this is the buffer in which the status line text is placed. 


For the BKM_QUERYTABTEXT message, this is the buffer in which the tab text is 
placed. 


textLen (ULONG) 
String length. 


Length of the text string. For the BKM_QUERYSTATUSLINETEXT message, this is the 
length of the status line text string. 


For the BKM_QUERYTABTEXT message, this is the length of the tab text string. 
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BTNCDATA 


Button-control-data structure. 


Syntax 


Fields 
cb (USHORT) 
Length of the control data in bytes. 


This is the length of the control data for a button control. 


fsCheckState (USHORT) 
Check state of button. 


This is the same value as returned by the BM_QUERYCHECK message and passed to 
the BM_SETCHECK message. 


fsHiliteState (USHORT) 
Highlighting state of button. 


This is the same value as returned by the BM_QUERYHILITE message and passed to 
the BM_SETHILITE message. 


himage (LHANDLE) 
Resource handle for icon or bit map. 


BYTE 
A byte. 


Syntax 
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CATCHBUF 


Saved execution environment buffer. 


Syntax 


“typedef struct CATCHBUF { 


reserved[4]; _ 


Fields 
reserved[4] (ULONG) 
Save area. 


CDATE 
Structure that contains date information for a data element in the details view of a container 
control. 


Syntax 


Fields 
day (UCHAR) 
Current day. 


month (UCHAR) 
Current month. 


year (USHORT) 
Current year. 
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CHAR 


Single-byte character. 


Syntax 


CHARBUNDLE 


Character-attributes bundle structure. 


Syntax 


Fields 
iColor (LONG) 
Character foreground color. 


IBackColor (LONG) 
Character background color. 


usMixMode (USHORT) 
Character foreground-mix mode. 


usBackMixMode (USHORT) 
Character background-mix mode. 


usSet (USHORT) 
Character set. 
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usPrecision (USHORT) 
Character precision. 


sizfxCell (SIZEF) 
Character cell size. 


ptlAngle (POINTL) 
Character angle. 


ptiShear (POINTL) 
Character shear. 


usDirection (USHORT) 
Character direction. 


usTextAlign (USHORT) 
Text alignment. 


fxExtra (FIXED) 
Character extra. 


fxBreakExtra (FIXED) 
Character break extra. 


CLASSINFO 


Class-information structure. 


Syntax 


| typedef struct _CLASSINFO { 
ULONG -flClassStyle; [ 
PFNWP_—s pfnWindowProc; 
ULONG > edad au 
y CLASSINFOS ; ue 


‘typed CLASSINO *PCLASSINO; 


Fields 
flClassStyle (ULONG) 
Class-style flags. 


pfnWindowProc (PFNWP) 
Window procedure. 


cbhWindowData (ULONG) 


Number of additional window words. 
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CNRDRAGINFO 


Structure that contains information about a direct manipulation event that is occurring over. 
the container. The information specified for this structure depends on the container 
notification code with which it is used. The differences are specified in the following field 
descriptions. The applicable notification codes are: 


e “CN _DRAGAFTER’ on page 22-12 
e “CN _DRAGLEAVE” on page 22-15 
e “CN _DRAGOVER’ on page 22-16 

e “CN DROP” on page 22-18 

e “CN _DROPHELP” on page 22-19 


Syntax 


def CNRDRAGINFO *PCNRORAGINFO; 


Fields 
pDraginfo (PDRAGINFO) 
Pointer to a DRAGINFO structure. 


pRecord (PRECORDCORE) 
Pointer to a RECORDCORE structure. 


The structure that is pointed to depends on the notification code being used. 


Note: If the CCS _MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data 
structures and messages. For the CN_DRAGAFTER notification code, this field contains 
a pointer to the RECORDCORE structure after which ordered target emphasis is drawn. 
If ordered target emphasis is applied above the first record in item order, the CM_FIRST 
attribute is returned. 


For the CN_DRAGLEAVE notification code, this field is NULL. 


For the CN DRAGOVER, CN_DROP, and CN_DROPHELP notification codes, this field 
contains a pointer to a container record over which direct manipulation occurred. This 
field has a value of NULL if the direct manipulation event occurs over white space. 


‘CNRDRAWITEMINFO 
Structure that contains information about the container item being drawn. This structure is 
used with the WM_DRAWITEM (in Container Controls) message only. See 
“WM_DRAWITEM (in Container Controls)” on page 22-7 for information about that message. 
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Syntax 


typedef struct ~CNRDRAWITEMINEO. { 
PRECORDCORE . pRecord; : 
PFIELDINFO pFieldInfo; 
} CNRDRAWITEMINFO; 


typedef CNRDRAWITEMINFO *PCNRDRAWITEMINFO; 


Fields 
pRecord (PRECORDCORE) 
Pointer to the RECORDCORE structure for the record being drawn. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE 
and PMINIRECORDCORE should be used instead of PRECORDCORE in all 
applicable data structures and messages. 


pFieldinfo (PFIELDINFO) 
Pointer to the FIELDINFO structure for the container column being drawn in the details 
view. 


For all other views, this field is NULL. 


CNREDITDATA 


Structure that contains information about the direct editing of container text. The information 
specified for this structure depends on the container notification code or message with which 
it is used. The differences are specified in the following field descriptions. The applicable 
notification codes and message are: 


e “CN_BEGINEDIT” on page 22-10 
e “CN_ENDEDIT” on page 22-21 . 
e “CN _REALLOCPSZ’ on page 22-28 
e “CM_OPENEDIT” on page 22-54 
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Syntax 


Fields 
cb (ULONG) 
' Structure size. 


The size (in bytes) of the CNREDITDATA data structure. 


hwndCnr (HWND) 
Container window handle. 


pRecord (PRECORDCORE) 
Pointer to a RECORDCORE data structure, or NULL. 
This field is NULL if container titles are to be edited. 


Note: If the CCS _MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE 
and PMINIRECORDCORE should be used instead of PRECORDCORE in all 
applicable data structures and messages. 


For the CN_BEGINEDIT, CN_ENDEDIT, and CN_REALLOCPSZ notification codes, this 
field is a pointer to the edited RECORDCORE data structure. 


For the CM_OPENEDIT message, this field is a pointer to the RECORDCORE data 
structure to be edited. 


pFieldinfo (PFIELDINFO) 
Pointer to a FIELDINFO data structure, or NULL. 


Pointer to a FIELDINFO data structure if the current view is the details view and the user 
is not editing the container title. Otherwise, this field is NULL. 


If the current view is the details view: 


¢ For the CN_BEGINEDIT, CN_ENDEDIT, and CN_REALLOCPSZ notification codes, 
this field contains a pointer to the FIELDINFO structure being edited. 


e For the CM_OPENEDIT message, this field is a pointer to the FIELDINFO data 
structure to be edited. 
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ppszText (PSZ *) 
Pointer to a PSZ text string. 


For the CN_BEGINEDIT and CN_REALLOCPSZ notification codes, this field is a pointer 
to the current PSZ text string. 


For the CN_ENDEDIT notification code, this field is a pointer to the new PSZ text string. 
For the CM_OPENEDIT message, this field is NULL. 


cbText (ULONG) 
Number of bytes in the text string. 


For the CN_BEGINEDIT notification code, this field is 0. 


For the CN_ENDEDIT and CN_REALLOCPSZ notification codes, this field is the number 
of bytes in the new text string. 


For the CM_OPENEDIT message, this field is 0. 


id (VULONG) 
ID of the window to be edited. 


The ID can be one of the following: 


CID_CNRTITLEWND 

Title window. 
CID_LEFTDVWND 

Left details view window; default if unsplit window. 
CID_RIGHTDVWND 

Right details view window. 
CID_LEFTCOLTITLEWND 

Left details view column headings window; default if unsplit window. 
CID_RIGHTCOLTITLEWND 

Right details’ view column headings window. 
An application-defined container-ID 

Container window. 
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CNRDRAGINIT 


A-32 


Structure that contains information about a direct manipulation event that is initiated in a 
container. This structure is used with the CN_INITDRAG notification code only. See 
“CN_INITDRAG?” on page 22-24 for information about that notification code. 


ele 


“typedef struct _CNRORAGINET 
HWND = hwndCor 
"PRECORDCORE _ pRecord; 
LONG : oo 
LONG eee 

LONG Cys 

4 CNRDRAGINIT; 


typedef ENRORAGINIT »PCNRORAGINITS 


Fields 
hwndCnr (HWND) 
Container control handle. 


pRecord (PRECORDCORE) 
Pointer to the RECORDCORE where direct manipulation started. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data 
structures and messages. 


The pRecord field can have one of the following values: 


NULL Direct manipulation started over white space. 
Other Container record over which direct manipulation started. 


x (LONG) 
X-coordinate of the pointer of the pointing device in desktop coordinates. 


y (LONG) 
Y-coordinate of the pointer of the pointing device in desktop coordinates. 


cx (LONG) . 
X-offset from the hot spot of the pointer of the pointing device (in pels) to the record 
origin. . 

cy (LONG) 


Y-offset from the hot spot of the pointer of me pointing device un pels) to the record 
origin. 
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CNRINFO 


Structure that contains information about the container. 


Syntax 


typedef struct SENRENED { 

ULONG cb; el 

PVOID. pSortRecord; 
“PFIELDINFO pFieldinfolast; 

PFIELDINFO pFieldInfo0bject; 

PSZ _ psz€nrTitle; 

ULONG - flWindowAttr; 

POINTL ptlOrigin; 

ULONG cDelta; 

ULONG cRecords; 

SIZEL s1BitmapOrIcon; 

SIZEL slTreeBitmapOrIcon; 
- HBITMAP hbmExpanded; 

HBITMAP ~hbmCol lapsed; 

HPOINTER. hptrExpanded; 
—HPOINTER hptrCol lapsed; 
LONG. cyLineSpacing; 
LONG. exTreeIndent; 
LONG cxTreeLine; 
~ ULONG cFields; 

LONG xVertSplitbar; 
e) CNRINFO; 


_Upedet CNRTNEO *PCNRINFO; 


Fields 
cb (ULONG) 
Structure size. 


The size (in bytes) of the CNRINFO data structure. 


pSortRecord (PVOID) 
Pointer to the comparison function for sorting container records, or NULL. 


If NULL, which is the default condition, no sorting is performed. Sorting only occurs 
during record insertion and when changing the value of this field. The third parameter of 
the comparison function, pStorage, must be NULL. See “CM_SORTRECORD?” in the 
Presentation Manager Programming Reference for a further description of the 
comparison function. 


pFieldinfoLast (PFIELDINFO) 
Pointer to last column in the left window of the split details view, or NULL. 


The default is NULL, causing all columns to be positioned in the left window. 
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pFieldinfoObject (PFIELDINFO) 
Pointer to a column that represents an object in the details view. 


The data for this FIELDINFO structure must contain icons or bit maps. In-use emphasis 
is applied to this column of icons or bit maps only. The default is the leftmost column in 
the unsplit details view, or the leftmost column in the left window of the split details view. 


pszCnrTitle (PSZ) 
Title text, or NULL. 


Text for the container title. The default is NULL. 


flWindowAttr (ULONG) 
Window attributes. 


Consists of the following container window attributes: 


* Specify one of the following container views, which determine the presentation 
format of items in a container: 


CV_ICON 
In the icon view, the container items are represented as icon/text or bit-map/text 
pairs, with text beneath the icons or bit maps. This is the default view. This 
view can be combined with the CV_MINI style bit by using an OR operator (\). 
See CV_MINI on page A-35 for more information. 


CV_NAME 
In the name view, the container items are represented as icon/text or 
bit-map/text pairs, with text to the right of the icons or bit maps. This view can 
be combined with the CV_MINI and CV_FLOW style bits by using OR operators 
(|). See CV_MINI on page A-35 and CV_FLOW on page A-35 for more 
information. 


CV_TEXT 
In the text view, the container items are displayed as a list of text strings. This 
view can be combined with the CV_FLOW style bit by using an OR operator ((). 
See CV_FLOW on page A-35 for more information. 


CV_TREE 
In the tree view, the container items are represented in a hierarchical manner. ° 
The tree view has three forms, which are defined in the following list. If you 
specify CV_TREE by itself, the tree icon view is used. 


— Tree icon view 


The tree icon view is specified by using a logical OR operator to combine 
the tree view with the icon view (CV_TREE | CV_ICON). Container items 
in this view are represented as icon/text pairs or bit-map/text pairs, with text 
to the right of the icons or bit maps. Also, a collapsed or expanded icon or 
bit map is displayed to the left of parent items. If this icon or bit map is a 
collapsed icon or bit map, selecting it will cause the parent item to be 
expanded so that its child items are displayed below it. If this icon or bit 
map is an expanded icon or bit map, selecting it will cause the parent’s 
Child items to be removed from the display. The default collapsed and 
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expanded bit maps provided by the container use a plus sign (+) anda 
minus sign (-), respectively, to indicate that items can be added to or 
subtracted from the display. 


— Tree name view 


The tree name view is specified by using a logical OR operator to combine 
the tree view with the name view (CV_TREE | CV_NAME). Container 
items in this view are displayed as either icon/text pairs or bit-map/text 
pairs, with text to the right of the icons or bit maps. However, the indicator 
that represents whether an item can be collapsed or expanded, such as a 
plus or minus sign, is included in the icon or bit map that represents that 
item, not in a separate icon or bit map as in the tree icon and tree text 
views. The container control does not provide default collapsed and 
expanded bit maps for the tree name view. 


— Tree text view 


The tree text view is specified by using a logical OR operator to combine 
the tree view with the text view (CV_TREE | CV_TEXT). Container items 
in this view are displayed as a list of text strings. As in the tree icon view, a 
collapsed or expanded icon or bit map is displayed to the left of parent 
items. 


CV_DETAIL 
In the details view, the container items are presented in columns. Each column 
can contain icons or bit maps, text, numbers, dates, or times. 


° Specify one or both of the following view styles by using an OR operator (|) to 
combine them with the specified view. These view styles are optional. 


CV_MINI 
Produces a mini-icon whose size is based on the Presentation Manager (PM) 
SV_CYMENU system value to produce a device-dependent mini-icon. 


The CV_MINI view style bit is ignored when: 


— The text view (CV_TEXT), tree view (CV_TREE), or details view 
(CV_DETAIL) are displayed 


— The CCS_MINIRECORDCORE style bit is specified. 


If this style bit is not specified and the icon view (CV_ICON) or name view 
(CV_NAME) is used, the default, regular-sized icon is used. The size of 
regular-sized icons is based on the value in the s/BitmapOricon field of the 
CNRINFO data structure. If this field is equal to 0, the PM SV_CXICON and 
SV_CYICON system values for width and height, respectively, are used. Icon 
sizes are consistent with PM-defined icon sizes for all devices. 


CVv_FLOW 
Dynamically arranges container items in columns in the name and text views. 
These are called flowed name and flowed text views. If this style bit is set for 
the name view (CV_NAME) or text view (CV_TEXT), the container items are 
placed in a single column until the bottom of the client area is reached. The 
next container item is placed in the adjacent column to the right of the filled 
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column. This process is repeated until all of the container items are positioned 
in the container. The width of each column is determined by the longest text 
string in that column. The size of the window determines the depth of the client 
area. 


If this style bit is not specified, the default condition for the name and text views 
is to vertically fill the container in a single column without flowing the container 
items. If this style bit is set for the icon view (CV_ICON) or details view 
(CV_DETAIL), it is ignored. 


¢ Specify either of the following to indicate whether the container will display icons or 
bit maps: 


CA_DRAWICON 
Icons are used for the icon, name, tree, or details views. This is the default. 
This container attribute should be used with the hptricon and hptrMinilcon fields 
of the RECORDCORE data structure. 


CA_DRAWBITMAP 
Bit maps are used for the icon, name, tree, or details views. This container 
attribute can be used with the hbmBitmap and hbmMiniBitmap fields of the 
RECORDCORE data structure. © 


Notes: 


1. If both the CA_DRAWICON and CA_DRAWBITMAP attributes are specified, 
the CA_DRAWICON attribute is used. 


2. If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, the hptricon field of the MINIRECORDCORE data structure is 
used. 


¢ Specify one of the following attributes to provide target emphasis for the name, text, 
and details views. If neither ordered nor mixed target emphasis is specified, the 
emphasis is drawn around the record. 


CA_ORDEREDTARGETEMPH 
Shows where a container record can be dropped during direct manipulation by 
drawing a line beneath the record. Ordered target emphasis does not apply to 
the icon and tree views. 


CA_MIXEDTARGETEMPH 
Shows where a container record can be dropped during direct manipulation 
either by drawing a line between two items or by drawing lines around the 
container record. Mixed target emphasis does not apply to the icon and tree 
views. 


e Specify the following attribute to draw lines that show the relationship between items 
in the tree view. 


CA_TREELINE 
Shows the relationship between all items in the tree view. 
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Specify the following to draw container records, paint the background of the 
container, or both: 


CA_OWNERDRAW 
Ownerdraw for the container, which allows the application to draw container 
records. 


CA_OWNERPAINTBACKGROUND 
Allows the application to subclass the container and paint the background. If 
specified, and the container is subclassed, the application receives the 
CM_PAINTBACKGROUND message in the subclass procedure. Otherwise, the 
container paints the background using the color specified by 
SYSCLR_WINDOW, which can be changed by using the 
PP_BACKGROUNDCOLOR or PP_BACKGROUNDCOLORINDEX presentation 
parameter in the WM_PRESPARAMCHANGED (in Container Controls) 


Specify the following if the container is to have a title: 


CA_CONTAINERTITLE 
Allows you to include a container title. The default is no container title. 


Specify one or both of the following container title attributes. These are valid only if 
the CA_CONTAINERTITLE attribute is specified. 


CA_TITLEREADONLY 
Prevents the container title from being edited directly. The default is to allow the 
container title to be edited. 
CA_TITLESEPARATOR 
Puts a separator line between the container title and the records beneath it. 
The default is no separator line. 


Specify one of the following to position the container title. These are valid only if 
the CA_CONTAINERTITLE attribute is specified. 


CA_TITLECENTER 
Centers the container title. This is the default. 


CA_TITLELEFT 
Left-justifies the container title. 


CA_TITLERIGHT 
Right-justifies the container title. 


Specify the following to display column headings in the details view: 


CA_DETAILSVIEWTITLES 
Allows you to include column headings in the details view. The default is no 
column headings. 
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ptlOrigin (POINTL) 
_ Workspace origin. 


Lower-left origin of the workspace in virtual coordinates, used in the icon view. The 
default origin is (0,0). 


cDelta (ULONG) 
Threshold. 


An application-defined threshold, or number of records, from either end of the list of 
available records. Used when a container needs to handle large amounts of data. The 
default is 0. Refer to the OS/2 Programming Guide for more information about 
specifying deltas. 


cRecords (ULONG) 
Number of records. 


The number of records in the container. Initially this field is 0. 


sIBitmapOricon (SIZEL) 
Icon/bit-map size. 


The size (in pels) of icons or bit maps. The default is the system size. 
slTreeBitmapOricon (SIZEL) 

Icon/bit-map size. 

The size (in pels) of the expanded and collapsed icons or bit maps used in the tree icon 

and tree text views. 


hbmExpanded (HBITMAP) 
Bit-map handle. 


The handle of the bit map to be used to represent an expanded parent item in the tree 
icon and tree text views. If neither an icon handle (see hptrExpanded) nor a bit-map 
handle is specified, a default bit map with a minus sign (-) is provided. 


hbmColiapsed (HBITMAP) 
Bit-map handle. 


The handle of the bit map to be used to represent a collapsed parent item in the tree 
icon and tree text views. If neither an icon handle (see hptrCollapsed) nor a bit-map 
handle is specified, a default bit map with a plus sign (+) is provided. . 


hptrExpanded (HPOINTER) 
Icon handle. 


The handle of the icon to be used to represent an expanded parent item in the tree icon 
and tree text views. If neither an icon handle nor a bit-map handle (see hbmExpanded) 
is specified, a default bit map with a minus sign (-) is provided. 
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hptrCollapsed (HPOINTER) 
Icon handle. 


The handle of the icon to be used to represent a collapsed parent item in the tree icon 
and tree text views. If neither an icon handle nor a bit-map handle (see hbmCollapsed) 
is specified, a default bit map with a plus sign (+) is provided. 


cyLineSpacing (LONG) 
Vertical space. 


The amount of vertical space (in pels) between the records. If you specify a value that 
is less than 0, a default value is used. 


cxTreeindent (LONG) 
Horizontal space. 


The amount of horizontal space (in pels) between levels in the tree view. If you specify 
a value that is less than 0, a default value is used. 


cxTreeLine (LONG) 
Line width. 


The width of the lines (in pels) that show the relationship between tree items. If you 
specify a value that is less than 0, a default value is used. Also, if the CA_TREELINE 
container attribute of the f/WindowAitr field is not specified, these lines are not drawn. 


cFields (ULONG) 
Number of columns. 


The number of FIELDINFO structures in the container. Initially this field is 0. 


xVertSplitbar (LONG) 
Split bar position. 
The initial position of the split bar relative to the container, used in the details view. If 
this value is less than 0, the split bar is not used. The default value is negative one 


(-1). 


CNRLAZYDRAGINFO 


Container lazy drag information. 


Syntax 


typedef struct _CNRLAZYDRAGINFO { = 
PDRAGINFO ~—sopDragInfo; 
 PRECORDCORE —s pRecord; 
HWND = shwndlarget; 
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Fields 
pDraginfo (PDRAGINFO) 
Pointer to the DRAGINFO structure. 


pRecord (PRECORDCORE) 
Pointer to a container RECORDCORE structure. 


A value of NULL indicates that the lazy drag set was dropped over whitespace in the 
container. Any other value indicates that the lazy drag set was dropped on the record 
specified by this field. 


hwndTarget (HWND) 
Handle of the target winddow that the lazy drag set was dropped on. 


COLOR 


Color value. 


Syntax 


CONVCONTEXT 


Dynamic-data-exchange conversation context structure. 


Syntax 


Fields 
cb (ULONG) 
Length of structure. 


This must be set to the length of the CONVCONTEXT structure. 
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fsContext (ULONG) 
Options. 


DDECTXT_CASESENSITIVE _ All strings in this conversation are case sensitive. 


idCountry (ULONG) 
Country code. 


usCodepage (ULONG) 
Code-page identity. 


usLangID (ULONG) 
Language. 


Zero is valid and means no language information. 


usSubLangID (ULONG) 
Sub-language. 


Zero is valid and means no sub-language information. 


CREATESTRUCT 


Create-window data structure. 


Syntax 


/ edef struct _CREATESTRUCT u 
pPresParams 
ee 


#: : 
2 he 


iStyles 
> pszlext:. 
_ ps2zCl assName; 


Fields 
pPresParams (PVOID) 
Presentation parameters. 


pCtiData (PVOID) 
Control data. 


Appendix A. Data Types A-41 


id (ULONG) 
Window identifier. 


hwndinsertBehind (HWND) 
Window behind which the window is to be placed. 


hwndOwner (HWND) 
Window owner. 


cy (LONG) 
Window height. 


cx (LONG) 
Window width. 


y (LONG) 
Y-coordinate of origin. 


x (LONG) 
X-coordinate of origin. 


fiStyle (ULONG) 
Window style. 


pszText (PSZ) 
Window text. 


f 


pszClassName (PSZ) 
Registered window class name. 


hwndParent (HWND) 
Parent window handle. 


CSBITMAPDATA 


This is the bit-map data structure for the circular slider buttons. 


Syntax 
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Fields 
hbmLeftUp (HBITMAP) 
Handle to the “up” position bit map for the button on the left. 


hbmLeftDown (HBITMAP) 
Handle to “down” position bit map for the button on the left. 


hmbRightUp (HBITMAP) 
Handle to the “up” position bit map for the button on the right. 


hbmRightDown (HBITMAP) 
Handle to the “down” position bit map for the button on the right. 


CURSORINFO 


Cursor-information structure. 


Syntax 


_ typedef struct _CURSORINFO { 
HWND———shwnd 
LONG” x; 

LONG y; 

LONG CX; 

LONG cy3 
ULONG | fs; 

RECTL - relClips 

- } CURSORINFO; 


| typedef CURSORINFO *PCURSORINFO; 


Fields 
hwnd (HWND) 
Window handle. 


x (LONG) 
X-coordinate. 


y (LONG) 
Y-coordinate. 


cx (LONG) 
Cursor width. 


cy (LONG) 
Cursor height. 


fs (ULONG) 
Options. 
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rciClip (RECTL) 
Cursor box. 


CTIME 


Structure that contains time information for a data element in the details view of a container 
control. 


Syntax 


Fields 
hours (UCHAR) 
Current hour. 


minutes (UCHAR) 
Current minute. 


seconds (UCHAR) 
Current second. 


ucReserved (UCHAR) 
Reserved. 


Control-Data 


Pointer to class-specific control data, beginning with a value conforming to a USHORT data 
type, which specifies the overall length of the data. 


There are several different types of control-data structures: 


BTNCDATA Button control data 
ENTRYFDATA Entry field control data 
FRAMECDATA Frame control data 
MLECTLDATA Multi-line entry field control data 
SBCDATA Scroll bar control data. : 
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DDEINIT 


Dynamic-data-exchange initiation structure. 


Syntax 


typeder struct _DDEINIT e 

PST neeRocNee: oe 
PSZ -.. -pszTopic; = 
ULONG offConvContext; 
uy DDEINIT;. 


“typedef 1 pDEINGT *PDDEINIT; 


Fields 
cb (ULONG) 
Length of structure. 


This must be set to the length of the DDEINIT structure. 


pszAppName (PSZ) 
Application name. 


Pointer to name of the server application. 


Application names must not contain slashes or backslashes. These characters are 
reserved for future use in network implementations. 


pszTopic (PSZ) 
Topic. 


Pointer to name of the topic. 


offConvContext (ULONG) 
Conversation context. 


Offset to a CONVCONTEXT structure. 
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DELETENOTIFY 
Structure that contains information about the application page that is being deleted from a 
notebook. 


Syntax 


Fields 
hwndBook (HWND) 
Notebook window handle. 


hwndPage (HWND) 
Application page window handle. 


ulAppPageData (ULONG) 
Application-specified page data. 


hbmTab (HBITMAP) 
Application-specified tab bit map. 


DDESTRUCT 


Dynamic-data-exchange control structure. 


Syntax 
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Fields 
cbData (ULONG) 
Length of the data. 


This is the length of data that occurs after the offabData parameter. If no data exists, 
this field should contain a zero (0). 


fsStatus (USHORT) 
Status of the data exchange. 


DDE_FACK Positive acknowledgement 

DDE_FBUSY Application is busy 

DDE_FNODATA No data transfer for advise 

DDE_FACKREQ Acknowledgements are requested 

DDE_FRESPONSE Response to WM_DDE_REQUEST 

DDE_NOTPROCESSED DDE message not understood 

DDE_FAPPSTATUS A 1-byte field of bits that are reserved for application-specific 
returns. 


usFormat (USHORT) 
Data format. 


One of the DDE data formats. 


DDEFMT_TEXT Text format. 

Other DDE format registered with the atom manager, using the system 
atom table. The predefined DDE formats are guaranteed not to 
conflict with the values returned by the atom manager. 


offszitemName (USHORT) 
Offset to item name. 


This is the offset to the item name from the start of this structure. Item name is a null 
(0x00) terminated string. If no item name exists, there must be a single null (0x00) 
character in this position. (That is, temName is ALWAYS a null terminated string.) 


offabData (USHORT) 
Offset to beginning of data. 


This is the offset to the data, from the start of this structure. This field should be 
calculated regardless of the presence of data. If no data exists, cbData must be zero 


(0). 


For compatibility reasons, this data should not contain embedded pointers. Offsets 
should be used instead. 


Appendix A. Data Types A-47 


DESKTOP 


Desktop background state structure. 


Syntax 


_tupedet struct 0 _bESKTOP rt os 
“HBITNAP 


“Wtietoants ee 
oe es ce 
y DESKTOP; ee 


_typetet DESKTOP *PDESKTOP; | 


Fields 
cbSize (ULONG) 
Length of structure. 


hbm (HBITMAP) 
. Bit-map handle of desktop background. 


x (LONG) 
X desktop coordinate of the origin of the bit map. 


y (LONG) 
Y desktop coordinate of the origin of the bit map. 


fl (ULONG) 
Desktop background state indicators or setting options. 


SDT_CENTER The desktop background bit map is, or is to be, centered on the 
screen. If this option is specified, then the values of the x the y 
parameters are inapplicable. 

SDT_DESTROY Any existing desktop background bit map is to be destroyed. The 
setting of this option is not returned on the WinQueryDesktopBkgnd 
function. 

SDT_LOADFILE For the WinSetDesktopBkgnd function the bit map is to be loaded 
from the filename specified. If the SDT_NOBKGND flag is also set 
then the bit map is loaded but the background is not set. Tiling and 
scaling may be performed at load time or later when setting the bit 
map. 

SDT_NOBKGND There is no desktop background bit map, that is the design: 
background i a solid color. For the WinQueryDesktopBkgnd function . 
the existing background is to be left unmodified unless 
SDT_DESTROY is also specified. . 
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SDT_PATTERN __ The bit map represents a fill pattern. 


SDT_RETAIN The sZFile is, or is to be, remembered for use when the system is 
started. 

SDT_SCALE The bit map is, or is to be, scaled to fill the desktop. If this option is 
specified, then the values of the x and y parameters are inapplicable. 

SDT_TILE The bit map is, or is to be, tiled to fill the desktop. 


ITileCount (LONG) 
Number of images of the bit map to be tiled. 


The tile count is the number of images to be drawn in the vertical and horizontal 
direction when tiling the desktop background. 


szFile[260] (CHAR) 
Zero-terminated name of the file containing the bit map. 


DEVOPENSTRUC 


Open-device data structure. 


Syntax 


typedef struct _DEVOPENSTRUC { 

PSZ pszLogAddress; 

PSZ pszDriverName; - 

PDRIVDATA pdviv; 
pszDataType; 


PSZ : 
‘SZ 
PSZ 
PSZ 
PSZ 
SZ 


-._ pszNetworkPar. 
_ } DEVOPENSTRUC; a 


_ typedef DEVOPENSTRUC *PDEVOPENSTRUC; 


Fields 
pszLogAddress (PSZ) 
Logical address. 


This is required for an OD_DIRECT device being opened with DevOpenDC; it is the 
logical device address, such as “LPT1” on OS/2. Some drivers may accept a file name 
for this parameter, or even a named pipe. 


Where output is to be queued (for an OD_QUEUED device), this is the name of the 
queue for the output device. The queue name can be a UNC name. 


Note: This parameter can be a port name for a printer device context. 
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pszDriverName (PSZ) 
Driver name. . 


Character string identifying the printer driver, for example, LASERJET. The 
pszDriverName field of the PRQINFOS structure, associated with the required print 

_ queue, gives the driver and device name, separated by a period, for example 
LASERJET.HP LaserJet IIID It can contain only the name up to the period, for example 
LASERJET. . 


pdriv (PDRIVDATA) 
Driver data. 


Data that is to be passed directly to the PM device driver. Whether any of this is 
required depends upon the device driver. 


For printer device context, this is a pointer to the job properties data. 


pszDataType (PSZ) 
Data type. 


For a OD_QUEUED or OD_DIRECT device, this parameter defines the type of data that 
is to be queued as follows: 


PM_Q_STD Standard format 
PM_Q_RAW Raw format 


Note that a device driver can define other data types. 


For OD_QUEUED or OD_DIRECT defice types, the default is supplied by the device 
driver if pszDataType is not specified. For any other device type, pszDataType is 
ignored. 


pszComment (PSZ) 
~ Comment. 


Optional character string that the printer object displays to the user in a job settings 
notebook. It is recommended that the application include its own name in this comment 
string. 


Note: The job title text is derived from the document name passed to DevEscape 
(DEVESC_STARTDOC). 


pszQueueProcName (PSZ) 
Queue-processor name. 


This is the name of the queue processor for queued output, and is usually the defautt. 


pszQueueProcParams (PSZ) 
Queue-processor parameters. 


Queue processor parameters (optional). They can include information such as the 
number of copies you want to print and the size of the output area on the printed page. — 


The first parameter (COP) is used for all spool-file formats. The remaining parameters 
are valid for PM_Q_STD spool files only. Because PM_Q_STD data are used mainly for 
graphic data, these parameters are described in relation to the printing of picture files. 
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The PMPRINT/PMPLOT queue-processor parameters are separated by spaces and are: 


COP=n 
The COP parameter specifies the number of copies of the spool file that you want 
printed. The value of n must be an integer in the range of 1 through 999. 


The default is COP=7. 


ARE=C | w,h,/t 
The ARE parameter determines the ‘size and position of the output area. This is 
the area of the physical page to which printing is restricted. 


The default value of ARE=C means that the output area is the whole page. Note, 
however, that the printer cannot print outside its own device clip limits. 


To size and position the output area at a specific point on the page, use 
ARE=w,h,/,t, where: 


w, h are the width and height of the desired output area. 


At are the offsets of the upper-left corner of the output area from 
the left (I) and from the top (t) of the maximum output area. 


These four values must be given as percentages of the maximum output 
dimensions. The maximum output area is the area within the device clip limits. 


FIT=S | /t 
The F/T parameter determines which part of the picture is to be printed. You can 
request the whole of the picture, scaled to fit the output area; or you can position 
the picture (actual size) anywhere within the output area. This could mean that the 
picture is clipped at the boundaries of the output area. 


The default value of F/T=S causes the output to be scaled until the larger of the 
height or width just fits within the defined output area. The aspect ratio of the 
picture is maintained. 


To print the picture in actual size, use F/T=/,t, where /,t are the coordinates of the 
point in the picture that you want positioned at the center of the output area: / is 
measured from the left edge of the picture; and t is measured from the top edge. 
The coordinates must be given as percentages of the actual dimensions of the 
picture. 


XFMZ=0 | 1 
The XFM parameter enables you to override the picture-positioning and clipping 
instructions that are provided by the ARE and FIT parameters, including their 
defaults. 


The default value of XFM=7 allows the appearance of the output to be determined 
by the settings of the ARE and FIT parameters. 


A value of XFM=0 yields output as specified in the picture file. For example, 
applications that use many different forms can define different positions on each 
form for their output. 
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COL=M |. C 


The COL parameter enables you to specify color output if you have a color printer. 


A value of COL=M creates monochrome output (black foreground with no 
background color). This is supported by all devices. 


A value of COL=C creates color output. If you request color output on a 
monochrome device, the printer presentation driver tries to satisfy your request, 
which can cause problems because the only color available is black. For example, 
if the picture file specifies a red line on a blue background, both are drawn in black. 


The default is COL=M when you are addressing a monochrome printer and COL=C 
when you are addressing a color printer. 


MAP=N | A 


CDP 


The MAP parameter enables you to decide how the neutral colors (those that are 
not specified in the picture file) are printed. 


The default value of MAP=N yields a normal representation of the screen picture on 
a printed page, which means that the page background is white and the foreground 
is black. 


A value of MAP=A provides the reverse of the normal representation: the 
background is black and the foreground is white on the printed page. 


=codepage 

The CDP parameter overrides the codepage to being used for PM_Q_RAW print 
jobs. The print queue driver uses DEVESC_SETMODE to set the codepage, but 
not all printer drivers support this device escape. 


XLT=0 | 1 


The XLT parameter can eliminate the translation component when printing a 
metafile if XLT=17. 


When the resolution of the device is higher than that of the world coordinate space, 
a small translation of world coordinate point (0,0) occurs on the device to preserve 
the accuracy of the mapping from world to device coordinate units. For example, 
(0,0) becomes (1,1) if there are 3 pels to every world coordinate. 


Normally, this is not noticeable, but it can be a problem with some devices. For 
example, in order to draw a complete row of 80 characters using a device font, a . 
device may require the text to start at device coordinate position zero. Starting at a 
position other than zero may cause one or more characters at the end of the row to 
be clipped. In such cases, elimination of the translation is important and can be 
accomplished by specifying XLT=1. 


The default is XLT=0. 
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pszSpoolerParams (PSZ) 
Spooler parameters. 


Spooler parameters (optional) are separated by spaces. They are used for scheduling 
print jobs and are as follows: 


e The form names that identify the paper to be used, for example, FORM=A4,A5, ENV. 
The form names are optional; but if they are provided, the spooler is able to hold off 


printing 


the jobs until the required form is installed in the printer. !f the form name is 


not provided, the spooler attempts to print the job. The printer driver recognizes 
that there is a forms problem and displays a FORMS MISMATCH message box. 


e Priority 
integer 


of the print job, for example, PRTY=60. The priority is specified as an 
in the range 1 through 99; 99 is the highest. The default priority value is 50. 


The application can use the spooler priority parameter to prioritize its own jobs; 
however, it is not good practice for an application always to use priority 99 in an 


attempt 


to get its jobs printed first. 


pszNetworkParams (PSZ) 
Network parameters. 


Optional parameter that can be used to specify network options; for example, 
USER=JOESMITH. 


DLGTEMPLATE 


Dialog-template structure. 


Syntax 


| typedef struct 
USHORT => 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 

| USHORT 
~DLGTITEM 


“DLGTEMPLATE { — 
cbTemplate; — 


type; 
- codepage; 


offadigti; 


 fsTemplateStatus; 
- ditemFocus; 

— -coffPresParams; 
-adigti[l]; - 


-} DLGTEMPLATE; 


typedef DLGTEMPLATE *PDLGTEMPLATE; — 


Fields 


cbTemplate (USHORT) 
Length of template. 


type (USHORT) 


Template format type. 
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codepage (USHORT) 
Code page. 


offadigti (USHORT) 
Offset to dialog items. 


fsTemplateStatus (USHORT) 
Template status. 


ilttemFocus (USHORT) 
Index of item to receive focus initially. 


coffPresParams (USHORT) 
Count of presentation-parameter offsets. 


adigti[1] (ODLGTITEM) 
Start of dialog items. 


DLGTITEM 


Dialog-item structure. 


Syntax 


sp tava 


2 
: 
a 
& 


eS 


ee 
eee 


ee 
Sean ee Seer iibe 
PSR O ROE Ge PEE 
eo ee 
ee 
Oo s ee 
See 
see ogee 
Pease ue 
oe 


Fields 
fsitemStatus (USHORT) 


Status. 


cChildren (USHORT) 
Count of children to this dialog item. 


e 
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ee 


ee 
Bee 


ee a 
BORE eae ee 


Dear ee ie 
enbaihtnmettaacnaa tote 

tone Ea eee 

po astern eet, 

ee eee 
oe 


Ses 
sees 


cchClassLen (USHORT) 
Length of class name. 


If zero, offClassName contains the hexadecimal equivalent of a preregistered class 
name.. 


offClassName (USHORT) 
Offset to class name. 


If cchClassLen is nonzero, this is the offset to a null-terminated ASCII string that 
contains the classname. If cchClassLen is zero, this is of the form Oxhhhh, where hhhh 
is the hexadecimal equivalent of the preregistered class name. 


cchTextLen (USHORT) 
Length of text. 


offfext (USHORT) 
Offset to text. 


fiStyle (ULONG) 
Dialog item window style. 


The high-order 16 bits are the standard WS * style bits. The low-order 16 bits are 
available for class-specific use. 


x (SHORT) 
X-coordinate of origin of dialog-item window. 


y (SHORT) 
Y-coordinate of origin of dialog-item window. 


cx (SHORT) 
Dialog-item window width. 


cy (SHORT) 
Dialog-item window height. 


id (USHORT) 
Identity. 


offPresParams (USHORT) 
Reserved. 


offCtiData (USHORT) 
Offset to control data. 
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DRAGIMAGE 


Dragged-object-image structure which describes the images that are to be drawn under the 
direct-manipulation pointer for the duration of a drag operation. 


| Syntax 
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Fields 
cb (USHORT) 
Size, in bytes, of the DRAGIMAGE structure. 


cptl (USHORT) 
The number of points in the point array if ff is specified as DRG_POLYGON. 


himage (LHANDLE) 
Handle representing the image to display. 


The type is determined by ff. 


sizlStretch (SIZEL) 
Dimensions for stretching when ff is specified as DRG_STRETCH. 


fl (ULONG) 

Flags. 

DRG_ICON himage is an HPOINTER. 

DRG_BITMAP hIlmage is an HBITMAP. 

DRG_POLYGON himage is a pointer to an array of points that will be connected 

: with GpiPolyLine to form a polygon. The first point of the 

array should be (0,0), and the other points should be placed 
relative to this position. 

DRG_STRETCH If DRG_ICON or DRG_BITMAP is specified, the image is 
expanded or compressed to the dimensions specified by 
siziStretch. 


DRG_TRANSPARENT __ If DRG_ICON is specified, an outline of the icon is generated 
and displayed instead of the original icon. © 
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DRG_CLOSED If DRG_POLYGON is specified, a closed polygon is formed by 
moving the current position to the last point in the array before 
calling GpiPolyLine. 


cxOffset (SHORT) 
X-offset from the pointer hot spot to the origin of the image. 


cyOffset (SHORT) 
Y-offset from the pointer hot spot to the origin of the image. 


DRAGINFO 


Drag-information structure. 


Syntax 


Fields 
cbDraginfo (ULONG) 
Structure size, in bytes. 


The size includes the array of DRAGITEM structures. 


cbDragitem (USHORT) 
Size, in bytes, of each DRAGITEM structure. 
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usOperation (USHORT) 
Modified drag operations. 


An application can define its own modified drag operations for use when simulating a 
drop. These operations must have a value greater than DO_UNKNOWN. Possible 
values are described in the following list: 


DO_DEFAULT Execute the default drag operation. No modifier keys are pressed. 
DO_COPY Execute a copy operation. The Ctrl key is pressed. 

DO_LINK Execute a link operation. The Ctri+Shift keys are pressed. 
DO_MOVE Execute a move operation. The Shift key is pressed. 
DO_UNKNOWN An undefined combination of modifier keys is pressed. 


hwndSource (HWND) 
. Window handle of the source of the drag operation. 


xDrop (SHORT) 
X-coordinate of drop point expressed in desktop coordinates. 


yDrop (SHORT) 
Y-coordinate of drop point expressed in desktop coordinates. 


cditem (USHORT) 
Count of DRAGITEM structures. 


usReserved (USHORT) 
Reserved. 


DRAGITEM 


Drag-object structure. 


Syntax 
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Fields 
hwndltem (HWND) 


Window handle of the source of the drag operation. 


ulltemID (ULONG) 


Information used by the source to identify the object being dragged. 


hstrType (HSTR) 


String handle of the object type. 


The string handle must be created using the DrgAddStrHandle function. The string is of 


the form: 
type[,type...] 


The first type in the 


list must be the true type of the object. The following types are 


used by the OS/2* shell: 


DRT_ASM 
DRT_BASIC 
DRT_BINDATA 
DRT_BITMAP 
DRT_C 
DRT_COBOL 
DRT_DLL 
DRT_DOSCMD 
DRT_EXE 
DRT_FONT 
DRT_FORTRAN 
DRT_ICON 
DRT_LIB 
DRT_METAFILE 
DRT_OS2CMD 
DRT_PASCAL 
DRT_RESOURCE 
DRT_TEXT 
DRT_UNKNOWN 


hstrRMF (HSTR) 


Assembler code 
BASIC code 
Binary data 

Bit map 

C code 

COBOL code 
Dynamic link library 
DOS command file 
Executable file 
Font 

FORTRAN code 
Icon 

Library 

Metafile 

OS/2 command file 
Pascal code 
Resource file 

Text 

Unknown type. 


String handle of the rendering mechanism and format. 


The string handle must be created using the DrgAddStrHandle function. The string is of 


the form: 


mechfmt[,mechfmt...] 
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where mechfmt can be in either of the following formats: 


e <mechanism(1),format(1)> 
e (mechanism(1)[, mechanism(n)...]) x (format(1)[,format(n)...]) 


The first mechanism/format pair must be the native rendering mechanism and format of 
the object. 


Valid mechanisms are: 


“DRM_DDE” Dynamic data exchange 

“DRM_OBJECT” Item being dragged is a workplace object. 
“DRM_OS2FILE” OS/2 file 

“DRM_PRINT” Object can be printed using direct manipulation. 


Valid formats are: 


“DRF_BITMAP” OS/2 bit map 
“DRF_DIB” DIB 

“DRF_DIF” DIF 
“DRF_DSPBITMAP” Stream of bit-map bits 
“DRF_METAFILE” Metafile 
“DRF_OEMTEXT” OEM text 
“DRF_OWNERDISPLAY” Bit stream 
“DRF_PTRPICT” Printer picture 
“DRF_RTF” ~ Rich text 
“DRF_SYLK” SYLK 
“DRF_TEXT” Null-terminated string 
“DRF_TIFF” TIFF 
“DRF_UNKNOWN” Unknown format. 


_ hstrContainerName (HSTR) 
String handle of the name of the container holding the source object. 


The string handle must be created using the DrgAddStrHandle function. 


hstrSourceName (HSTR) 
String handle of the name of the source object. 


The string handle must be created using the DrgAddStrHandle function. 


hstrTargetName (HSTR) 
String handle of the suggested name of the object at the target. 


It is the responsibility of the source of the drag operation to create this string handle 
before calling DrgDrag. 


cxOffset (SHORT) 
X-offset from the pointer hot spot to the origin of the image that represents this object. 


This value is copied from cxOffset in the DRAGIMAGE structure by DrgDrag. 


cyOffset (SHORT) 
Y-offset from the pointer hot spot to the origin of the image that represents this object. 


This value is copied from cyOffset in the DRAGIMAGE structure by DrgDrag. 
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fsControl (USHORT) 
Source-object control flags. 


DC_OPEN Object is open 

DC_REF Reference to another object 

DC_GROUP - Group of objects 

DC_CONTAINER Container of other objects 

DC_PREPARE Source requires a DM_RENDERPREPARE message 


before it establishes a data transfer conversation 
DC_REMOVEABLEMEDIA Object is on removable media, or object cannot be 
recovered after a move operation. 


fsSupportedOps (USHORT) 
Direct manipulation operations supported by the source object. 


DO_COPYABLE Source supports DO_COPY 
DO_LINKABLE Source supports DO_LINK 
DO_MOVEABLE Source supports DO_MOVE. 


DRAGTRANSFER 


Drag-conversation structure. 


Syntax 


Sapeaer struct _DRAGTRANSFER {- 
~ ULONG ee Sebe = 
~-HWND - hwndClient; 

EM —pditem; 

:  yetrseleeteamns 
hstrRenderToName; 
“ ulvargetinfo; 
USHORT _ usOperation; 
- USHORT FsReplys 
; ne DRAGTRANSFER; : 


“typeder DRAGTRANSFER _*PDRAGTRANSFER; 
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Fields 
cb (ULONG) 
Size, in bytes, of the structure. 


hwndClient (HWND) 
Handle of the client window. 


This can be the target window or a window that represents an object in a container that 
was dropped on. 


pditem (PDRAGITEM) 
Pointer to the DRAGITEM structure that is to be rendered. 


This structure must exist within the DRAGINFO structure that was passed in the 
DM_DROP message. 


hstrSelectedRMF (HSTR) 
String handle for the selected rendering mechanism and format for the transfer 
operation. 


This handle must be created using DrgAddStrHandle. The target is responsible for 
deleting this handle when the conversation is complete. The string is in the format: 
<MECHANISM,FORMAT>. 


hstrRenderToName (HSTR) 
String handle representing the name where the source places, and the target finds, the 
data that is rendered. 


The target is responsible for deleting this string handle when the conversation 
terminates. The contents of this field vary according to the rendering mechanism. See 
hstrRMF field in DRAGITEM. 


OS/2 File The string handle represents the fully qualified name of the file where the 
rendering will be placed. 
DDE This field is not used. 
Print This field is not used. 
ulTargetinfo (ULONG) 
Reserved. 


Reserved for use by the target. The target can use this field for information about the 
object and rendering operation. 


usOperation (USHORT) 
The operation. 


Values are: 


DO_COPY —_ Execute a copy operation. 


DO_LINK Execute a link operation. 
DO_MOVE Execute a move operation. 
OTHER Execute an application-defined operation. 
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fsReply (USHORT) 
Reply flags. 


Replay flags for the message. These flags can be set as follows: 


DMFL_NATIVERENDER 


DMFL_RENDERRETRY 


DRIVDATA 


Driver-data structure. 


Syntax 


The source does not support rendering for this object. A 


- source should not set this flag unless it provides sufficient 


information at the time of the drop for the target to perform 
the rendering operation. The target must send 
DM_ENDCONVERSATION to the source after carrying out 
the rendering operation, or when it elects not to do a native 
rendering. 


The source supports rendering for the object, but does not 
support the selected rendering mechanism and format. The 
target can try another mechanism and format by sending 
another DM_RENDER message. If the target does not retry, 
it must send a DU_RENDERCOMPLETE message to the 
source. This flag is set in conjunction with the 
DMFL_NATIVERENDER flag. 


edef struct _DRIVDATA o as 
“be 


- szDeviceName[32]; oe 


-) DRIVDATAS 


oe eli: ae i 


- typedef DRIVOATA -+PORIVDATA; 2 _ 


Fields 
cb (LONG) 
Length. 


The length of the structure. 


lVersion (LONG) 
Version. 


The version number of the data. Version numbers are defined by particular PM device 


drivers. 
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szDeviceName[32] (CHAR) 
Device name. 


A string in a 32-byte field, identifying the particular device (model number, and so on). 
Again, valid values are defined by PM device drivers. 


abGeneralData[1] (CHAR) 
General data. 


Data as defined by the Presentation Manager device driver. 


The data type of this field is defined by the Presentation Manager device driver. It does 
not contain pointers, as these are not necessarily valid when passed to the device 
driver. 


ENTRYFDATA 


Entry-field control data structure. 


Syntax 


ty ae struct _ENTRYFOATA e 


: Sense 
SHOR ichMaxSel ; 
ENTRYFDATA: 


| typedet ENTRYFOATA *PENTRYFDATAS 


Fields 
cb (USHORT) 
Length of control data in bytes. 


The length of the control data for an entry field control. 


cchEditLimit (USHORT) 
Edit limit. 
This is the maximum number of characters that can be entered into the entry field 
control. 


If the operator tries to enter more text into an entry field control than is specified by the 
text limit set by the EM_SETTEXTLIMIT message, the entry field control indicates the 
error by sounding the alarm and does not accept the characters. . 


ichMinSel (USHORT) 
Minimum selection. 
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ichMaxSel (USHORT) 
Maximum selection. 


The ichMinSel and ichMaxSel! parameters identify the current selection within the entry 
field control. Characters within the text with byte offsets less than the ichMaxSel 
parameter and greater than or equal to the ichMinSe/ parameter are the current 
selection. The cursor is positioned immediately before the character identified by the 
ichMaxSel parameter. 


If the ichMinSel parameter is equal to the ichMaxSe/ parameter, the current selection 
becomes the insertion point. 


If the ichMinSel parameter is equal to 0 and the ichMaxSel is greater than or equal to 
text limit set by the EM_SETTEXTLIMIT message, the entire text is selected. 


ERRORID 
Error identity. 


Syntax 


: ypedef ULONG ERRORID; 


ERRINFO 


Error-information structure. 


Syntax 


typedef struct ERRINFO { 
—ULONG = =—scbF ixedErrinfo; 
 ERRORID. ._idError; 
ULONG —s cDetaillevel; 


el o 


+ edef ERRINFO *PERRINFO3 : 


Fields 
cbFixedErrinfo (ULONG) 
Length of fixed data to this structure. 


idError (ERRORID) 
Error identity. 


This is identical to the value returned by WinGetLastError. 
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cDetailLevel (ULONG) 
_ Number of levels of detail. 


This is the number of entries in the array of words pointed to by the following field. One 
level of detail is provided. 


offaoffszMsg (ULONG) : 
Offset to the array of message offsets. 


This is an offset to an array of 16-bit offsets to null-terminated strings. Each string is a 
printable message that offers varying levels of information. The first level is the least 
amount of detail, and the remaining levels offer more and more detail. 


The first level of detail is always an error message string, in the following format: 


XXxnnnns 


where XXX is the product identifier 

nnnn is the message number 

Ss is the message severity letter 
warning 
error” 
severe error 
unrecoverable 


cunm=e 
tou vw ou 


offBinaryData (ULONG) 
Offset to the binary data. 


This can contain additional information relating to the error. 


ESCMODE 
. Structure for setting printer mode. See DevEscape (DEVESC_SETMODE). 


Syntax 


typedef struct ESCWODE {0 
“ULONG = moder 
BYTE. modedata[1] ; oe 


|) EScMODE; 


typedef ESCMODE *PESCMODE; 


This data structure is a more-general version of the of the ESCSETMODE data structure. 
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Fields 
mode (ULONG) 
Mode. 


modedata[1] (BYTE) 
Mode data. 


ESCSETMODE 
Structure for setting printer mode. See DevEscape (DEVESC_SETMODE). 


Syntax 


typedef struct _ESCSETMODE { 
ULONG mode; 

USHORT codepage; 

} ESCSETMODE; 


“typedef ESCSETMODE *PESCSETMODE; 


This data structure is a specific-case version of the ESCMODE data structure, used to set 
the code page of a printer. 


Fields 
mode (ULONG) 
Mode to be set. 


0 Set mode to specified code page. Any font can be used. 


codepage (USHORT) 
Code page. 


If zero is specified for the code page, the printer is set to the hardware default. 


Appendix A. Data Types A-67 


FACENAMEDESC 


Face-name description structure. See GpiQueryFaceString. 


Syntax 


-USHORT 

USHORT =—susReserved; 
—ULONG Floptions;, oe 
oF FACENAMEDESC;, ee 


: typeder FACENANEDESC srRCENMEDESC 


Fields 
usSize (USHORT) 
Length of structure. 


usWeightClass (USHORT) 
Weight class. 


Indicates the visual weight (thickness of strokes) of the characters in the font: 


FWEIGHT_DONT_CARE Any font weight satisfies the request. 
FWEIGHT_ULTRA_ LIGHT Ultra-light. 
FWEIGHT_EXTRA_LIGHT Extra-light. 


FWEIGHT_LIGHT Light. 
FWEIGHT_SEMI_LIGHT Semi-light. 
FWEIGHT_NORMAL Medium (normal) weight. 
FWEIGHT_SEMI_BOLD Semi-bold. 

FWEIGHT_ BQLD Bold. 


FWEIGHT_EXTRA_BOLD Extra-bold. 
FWEIGHT_ULTRA_BOLD Ultra-bold. 


usWidthClass (USHORT) 
Width class. 


Indicates the relative aspect ratio of the characters of the font in relation to the normal 
aspect ratio for this type of font: 


FWIDTH_DONT_CARE Any font width satisfies the request. 
~ FWIDTH_ULTRA_CONDENSED Ultra-condensed (50% of normal). 
FWIDTH_EXTRA_CONDENSED Extra-condensed (62.5% of normal). 


FWIDTH_CONDENSED Condensed (75% of normal). 
FWIDTH_SEMI_CONDENSED Semi-condensed (87.5% of normal). 
FWIDTH_NORMAL Medium (normal). 
FWIDTH_SEMI_EXPANDED — Semi-expanded (112.5% of normal). 
FWIDTH_EXPANDED Expanded (125% of normal). 


A-68 PM Programming Reference Vol II 


FWIDTH_EXTRA_EXPANDED Extra-expanded (150% of normal). 
FWIDTH_ULTRA_EXPANDED Ultra-expanded (200% of normal). 


usReserved (USHORT) 


Reserved. 


flOptions (ULONG) 


Other characteristics of the font. 


FTYPE_ITALIC 


FTYPE_ITALIC_DONT_CARE 


FTYPE_OBLIQUE 


Italic font required. If not specified, non-italic font 
required. 


Italic and non-italic fonts can satisfy the request. If this 
option is specified, FTYPE_ITALIC is ignored. 


Oblique font required. If not specified, non-oblique font 
required. 


FTYPE_OBLIQUE_DONT_CARE Oblique and non-oblique fonts can satisfy the request. 


FTYPE_ROUNDED 


If this option is specified, FTYPE_OBLIQUE is ignored. 


Rounded font required. If not specified, non-rounded font 
required. 


FTYPE_ROUNDED_DONT_CARE Rounded and non-rounded fonts can satisfy the 


FATTRS 


Font-attributes structure. 


Syntax 


Cesare etruck _FATTRS { 


—USHORT 
-USHORT 


LONG © 


CHAR 

USHORT = 

USHORT. 

- . 1MaxBaselineExt 
: _ TAveCharWidth 

> fsiype: 

2 


| LONG 
LONG 


UsHORT 
—USHORT 
_} FATTRSS. 


__usRecordLength; 
_ fsSelection;. 
iMatch? oe 

_seFaconane[FACESIZE; oe 

idRegistry; oe 
-usCodePage; 


typed FATTRS. *PFATIR 


request. If this option is specified, FTYPE_ROUNDED 
is ignored. 
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Fields 
usRecordLength (USHORT) 
Length of record. 


fsSelection (USHORT) 
Selection indicators. 


Flags causing the following features to be simulated by the system. 


Note: If an italic flag is applied to a font that is itself defined as italic, the font is slanted 
further by italic simulation. 


Underscore or strikeout lines are drawn using the appropriate attributes (for 
example, color) from the character bundle (see the CHARBUNDLE datatype), not 
the line bundle (see LINEBUNDLE). The width of the line, and the vertical 
position of the line in font space, are determined by the font. Horizontally, the 
line starts from a point in font space directly above or below the start point of 
each character, and extends to a point directly above or below the escapement 
point for that character. 


For this purpose, the start and escapement points are those applicable to 
left-to-right or right-to-left character directions (see GpiSetCharDirection in 
Graphics Programming Interface Programming Reference), even if the string is 
currently being drawn in a top-to-bottom or bottom-to-top direction. 


For left-to-right or right-to-left directions, any white space generated by the 
character extra and character break extra attributes (see GpiSetCharExtra and 
GpiSetCharBreakExtra in Graphics Programming Interface Programming 
Reference), as well as increments provided by the vector of increments on 
GpiCharStringPos and GpiCharStringPosAt, are also underlined/overstruck, so 
that in these cases the line is continuous for the string. 


FATTR_SEL_ITALIC Generate italic font. 
FATTR_SEL_UNDERSCORE Generate underscored font. 
FATTR_SEL_BOLD Generate bold font. (Note that the resulting characters 


. .are wider than those in the original font.) 
FATTR_SEL_STRIKEOUT Generate font with everstruek characters. 
FATTR_SEL_OUTLINE Use an outline font with hollow characters. If this flag is 
not set, outline font characters are filled. Setting this © 
flag normally gives better performance, and for 
sufficiently small characters (depending on device 
resolution) there may be little visual difference. 


IMatch (LONG) 
Matched-font identity. 


szFacename[FACESIZE] (CHAR) 
Typeface name. 


The typeface name of the font, for example, Tms Rmn. 
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idRegistry (USHORT) 
Registry identifier. 


Font registry identifier (zero if unknown). 


usCodePage (USHORT) 
Code page. 


If zero, the current Gpi code page (see GpiSetCp in Graphics Programming Interface 
Programming Reference) is used. A subsequent GpiSetCp function changes the code 
page used for this logical font. 


IMaxBaselineExt (LONG) 
Maximum baseline extension. 


For raster fonts, this should be the height of the required font, in world coordinates. 


For outline fonts, this should be zero. 


lAveCharWidth (LONG) 
Average character width. 


For raster fonts, this should be the width of the required font, in world coordinates. 


For outline fonts, this should be zero. 


fsType (USHORT) 
Type indicators. 


FATTR_TYPE_KERNING Enable kerning (PostScript** only). 
FATTR_TYPE_MBCS Font for mixed single- and double-byte code pages. 
FATTR_TYPE_DBCS Font for double-byte code pages. 


FATTR_TYPE_ANTIALIASED  Antialiased font required. Only valid if supported by the 
device driver. 


fsFontUse (USHORT) 
Font-use indicators. 


These flags indicate how the font is to be used. They affect presentation speed and font 
quality. 


FATTR_FONTUSE_NOMIX Text is not mixed with graphics and can be 
written without regard to any interaction with 

graphics objects. 

FATTR_FONTUSE_ OUTLINE Select an outline (vector) font. The font 
characters can be used as part of a path 
definition. If this flag is not set, an outline 
font might or might not be selected. If an 
outline font is selected, however, character 
widths are rounded to an integral number of 
pels. 

FATTR_FONTUSE_TRANSFORMABLE _ Characters can be transformed (for example, 
scaled, rotated, or sheared). 
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FFDESCS 


Font-file descriptor. 


Syntax 


FIELDINFO 


_ Structure that contains information about column data in the details view of the container 
control. The details view displays each FIELDINFO structure as a column of data that 
contains specific information about each container record. For example, one FIELDINFO 
structure, or column, might contain icons or bit maps that represent each container record. 
Another FIELDINFO structure might contain the date or time that each container record was 
created. 


Syntax 


Fields 
cb (ULONG) 
Structure size. 


The size (in bytes) of the FIELDINFO structure. 
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flData (ULONG) 
Data attributes. 


Attributes of the data in a field. 


Specify one of the following for each column to choose the type of data that is 
displayed in each column: 


CFA_BITMAPORICON 
The column contains bit-map or icon data. 


CFA_DATE 
The data in the column is displayed in date format. National Language Support 
(NLS) is enabled for date format. Use the data structure described in CDATE 


CFA_STRING 
Character or text data is displayed in this column. 


CFA_TIME 


The data in the column is displayed in time format. National Language Support 
(NLS) is enabled for time format. Use the data structure described in CTIME. 


CFA_ULONG 
Unsigned number data is displayed in this column. National Language Support 
(NLS) is enabled for number format. 


Specify any or all of the following column attributes: 


CFA_FIREADONLY 
Prevents text in a FIELDINFO data structure (text in a column) from being edited 
directly. This attribute applies only to columns for which the CFA_STRING 
attribute has been specified. 


CFA_HORZSEPARATOR . 
A horizontal separator is provided beneath column headings. 


CFA_INVISIBLE 
Invisible container column. The default is visible. 


CFA_OWNER 
Ownerdraw is enabied for this container column. 


CFA_SEPARATOR 
A vertical separator is drawn after this column. 


Specify one of the following for each column to vertically position data in that 
column: 


CFA_BOTTOM 
Bottom-justifies field data. 


CFA_TOP 
Top-justifies field data. 


CFA_VCENTER 
Vertically centers field data. This is the default. 
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¢ Specify one of the following for each column to horizontally position data in that 
column. These attributes can be combined with the attributes used for vertical 
positioning of column data by using an OR operator (|). 


CFA_CENTER 
Horizontally centers field data. 


CFA_LEFT 
Left-justifies field data. This is the default. 


CFA_RIGHT 
Right-justifies field data. 


fiTitle (ULONG) 
Column heading attributes. 


¢ Specify the following if icon or bit-map data is to be displayed in the column 
heading: 


CFA_BITMAPORICON 
The column heading contains icon or bit-map data. If CFA_BITMAPORICON is 
not specified, any data that is assigned to a column heading is assumed to be 
character or text data. 


¢ Specify the following to prevent direct editing of a column heading: 
CFA_FITITLEREADONLY 
Prevents a column heading from being edited directly. 


¢ Specify one of the following for each column heading to vertically position data in 
that column heading: 


CFA_TOP 
Top-justifies column headings. 


CFA_BOTTOM 
Bottom-justifies column headings. 


CFA_VCENTER 
Vertically centers column headings. This is the default. 


¢ Specify one of the following for each column heading to horizontally position data in 
that column heading. These attributes can be combined with the attributes used for 
vertical positioning of column heading data by using an OR operator (|). 


CFA_CENTER 
Horizontally centers column headings. 


CFA_LEFT 
Left-justifies column headings. This is the default. 


CFA_RIGHT . 
Right-justifies column headings. 


pTitieData (PVOID) 
Column heading data. 


Column heading data, which can be a text string, or an icon or bit map. The default is a 
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text string. If the “Title field is set to the CFA_BITMAPORICON attribute, this must be 
an icon or bit map. 


offStruct (ULONG) 
Structure offset. 


Offset from the beginning of a RECORDCORE structure to the data that is displayed in 
this column. - 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data 
structures and messages. 


pUserData (PVOID) 
Pointer to user data. 


pNextFieldinfo (struct FIELDINFO *) — . 
Pointer to the next linked FIELDINFO data structure. 


cxWidth (ULONG) 
Column width. 


Used to specify the width of a column. The default is an automatically sized column that 
is always the width of its widest element. If this field is set and the data is too wide, the 
data is truncated. 


FIELDINFOINSERT 
Structure that contains information about the FIELDINFO structure or structures that are 
being inserted into a container. This structure is used in the CM_INSERTDETAILFIELDINFO 
container message only. See “CM_INSERTDETAILFIELDINFO” on page 22-44 for | 
information about that message. 


Syntax 


typedef struct uf TEEDINEOTIGERT. { 

ULONG =. = eb; me 

PFIELDINFO — -_ pFieldInfoOrder; oo 

ULONG = ~—._-« fiInvalidateFieldInfo; — 
-ULONG = cFieldInfolnsert; 

3 FIELDINFOINSERT; 


typeder FLELDINFOINSERT. _»PFIELDINFOINSERT; 


Fields 
cb (ULONG) 
Structure size. 


The size (in bytes) of the FIELDINFOINSERT structure. 
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pFieldInfoOrder (PFIELDINFO) 
Column order. 


Orders the FIELDINFO structure or structures relative to other FIELDINFO structures in 
the container. The values can be: 


CMA_FIRST Places a FIELDINFO structure, or list of FIELDINFO structures, at the 
front of the list of columns. 

CMA_END Places a FIELDINFO structure, or list of FIELDINFO structures, at the 
end of the list of columns. 

Other Pointer to a FIELDINFO structure that this structure, or list of structures, 
is to be inserted after. 


flnvalidateFieldInfo (ULONG) 
Update flag. 


Flag that indicates an automatic display update after the FIELDINFO structures are 
inserted. 


TRUE _ The display is automatically updated after FIELDINFO structures are inserted. 
FALSE The application must send the CM_INVALIDATEDETAILFIELDINFO message 
after the FIELDINFO structures are inserted. 


cFieldInfolnsert (ULONG) 
Number of columns. 


The number of FIELDINFO structures to be inserted. The cFieldinfoinsert field value 
must be greater than 0. 
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FILEDLG 


File-dialog structure. 


Syntax 


-HMODULE — —_—hMod; 
CHAR. oo SZEL 
PAPSZ = paps 
—ULONG isd 
‘USHORT = 
SHORT = =X; 
SHORT = 
SHORT 
J PILEDLG;: 


typedef FILEDLG 


Fields 
cbSize (ULONG) 
Structure size. 


Size of the structure. This field allows future expansion of the structure and must be 
initialized with the size of the FILEDLG structure. 
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fl (ULONG) 
FDS _* flags. 


Several flags can be specified to alter the behavior of the dialog. 


Note: The dialog must be either an “Open” or a “Save As” dialog. If neither the 
FDS_OPEN_DIALOG nor the FDS_SAVEAS_DIALOG flag is set, or if both are set, the 


dialog will return an error. 


FDS_APPLYBUTTON 
FDS_CENTER 
FDS_CUSTOM 


FDS_ENABLEFILELB 


FDS_FILTERUNION 


FDS_HELPBUTTON 


FDS_INCLUDE_EAS 


FDS_MODELESS 


FDS_MULTIPLESEL 
FDS_OPEN_DIALOG 


FDS _PRELOAD_VOLINFO 


FDS_SAVEAS DIALOG 


A-78 — PM Programming Reference Vol II 


An Apply push button is added to the dialog. . This is 
useful in a modeless dialog. 

The dialog is positioned in the center of its parent window, 
overriding any specified x, y position. 

A custom dialog template is used to create the dialog. 
The hMod and usDigID fields must be initialized. 

When this flag is set, the Files list box on a Save As 
dialog is enabled. When this flag is not set, the Files list 
box is not enabled for a Save As dialog. This is the 
default. 

When this flag is set, the dialog uses the union of the 
string filter and the extended-attribute type filter when 
filtering files for the Files list box. When this flag is not 
set, the list box, by default, uses the intersection of the 
two. 

A Help push button of style 
(BS_HELP|BS_NOPOINTERFOCUS) with an ID of 
DID_HELP_PB is added to the dialog. When this push 
button is pressed, a WM_HELP message is sent to 
hwndO. 


_ If this flag is set, the dialog will always query extended 


attribute information for files as it fills the Files list box. 
The default is to not query the information unless an 
extended attribute type filter has been selected. 

When this flag is set, the dialog is modeless; WinFileDlg 
returns immediately after creating the dialog window and 
returns the window handle to the application. The 
application should treat the dialog as if it were created 
with WinLoadDlg. As in the modal (default) dialog case, 
the return value is found in the /Return field of the 
FILEDLG structure passed to WinFileDlg. 

When this flag is set, the Files list box for the dialog is a 
multiple selection list box. When this flag is not set, the 
default is a single-selection list box. 

The dialog is an “Open” dialog when this flag is set. 

If this flag is set, the dialog will preload the volume 
information for the drives and will preset the current 
default directory for each drive. The default behavior is 
for the volume label to be blank and the initial directory 
will be the root directory for each drive. 

The dialog is a “Save As” dialog when this flag is set. 


ulUser (ULONG) 
Used by the application. 


This field can be used by an application that is subclassing the file dialog to store its 
own state information. 


IReturn (LONG) 
Result code. . 
Result code from dialog dismissal. This field contains the ID of the push button pressed 
to dismiss the dialog, DID_OK or DID_CANCEL, unless the application supplies 
additional push buttons in its template. If an error occurs on dialog invocation, this field 
is set to zero. 


ISRC (LONG) 
System return code. 


This field contains an FDS_ERR return code. When a dialog fails, this field is used to 
tell the application the reason for the failure. 


pszTitie (PSZ) 
Dialog title string. 
When this field is NULL, the dialog title defaults to the name of the dialog currently 
running. 


pszOKButton (PSZ) 
OK push button text. 


This string is used to set the text of the OK push button. The default text is OK. 


pfnDigProc (PFNWP) 
Custom dialog procedure. 


NULL unless the caller is subclassing the file dialog. When non-NULL, it points to the 
dialog procedure of the application. 


psziType (PSZ) 
Extended-attribute type filter. 


This field contains a pointer to the initial extended-attribute type filter that is applied to 
the initial dialog screen. This filter is not required to be in papsz/TypeList. 


papsziTypeList (PAPSZ) 
Pointer to a table of pointers to extended-attribute types. 


Each pointer in the table points to a null-terminated string, and each string is an 
extended-attribute type. These types are sorted in ascending order in the Type 
drop-down box. The end of the table is marked by a null pointer. To specify an empty 
table, the application sets this field to NULL, or it specifies a table containing only a null 
pointer. 
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pszlDrive (PSZ) 
The initial drive. 


This field contains a pointer to a string that specifies the initial drive applied to the initial 
dialog screen. This drive is not required to be in papsz/DriveList. 


papsziDriveList (PAPSZ) 
Pointer to a table of pointers to drives. 


Each pointer in the table points to a null-terminated string, and each string is a valid 
drive or network identifier. These drives and network IDs will be sorted in ascending 
order in the Drive drop-down box. The end of the table is marked by a null pointer. To 
specify an empty table, the application sets this field to NULL, or it specifies a table 
containing only a null pointer. 


hMod (HMODULE) 
Module for custom dialog resources. 


If FDS_CUSTOM is set, this is the HMODULE from which the custom file dialog 
template is loaded. NULLHANDLE causes the dialog resource to be pulled from the 
module of the current EXE. 


SZFullFile[(CCHMAXPATH] (CHAR) 
Character array. . 


An array of characters where CCHMAXPATH is a system-defined constant. On 
initialization, this field contains the initial fully-qualified path and file name. On 
completion, this field contains the selected fully-qualified path and file name. The simple 
file name can be replaced with a string filter, such as *.DAT.. When the dialog is 
invoked, all drive and path information is stripped from the entry and moved to the 
corresponding fields in the dialog. 


When a file name is specified, the Files list box is scrolled to the matching file name. 
When there is no exact match, the closest match is used. 


When a string filter is specified, the dialog is initially refreshed using the results of this 
filter intersected with the results of psz/Type. After the dialog is initially shown, the string 
filter remains in the file name field until a file is selected, or the user overtypes the value. 


When a file is selected, szFullFile is returned to the calling application and is set to the 
selected fully-qualified file name. 


When more than one file is selected in a multiple file selection dialog, only the topmost 
selected file name is returned in this field. 


papszFQFilename (PAPSZ) 
Pointer to a table of pointers to fully-qualified file names. 


Returned to multiple file selection dialogs when the user selects one or more files from 
the list box. If the user types the file name in the file name entry field, the file name will 
be in szFullFile and this pointer will be NULL. When one or more selections are made, 
the count of items in this array will be returned in u/FQFCount. 
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This table of pointers is storage allocated by the file dialog. When the application 
completes opening or saving all of the files specified, the application must call 
WinFreeFileDigList to free the storage allocated by the file dialog. 


ulFQFCount (ULONG) 
Number of file names. 


Number of file names selected in the dialog. In a single file selection dialog, this value 
is 1. In a multiple file selection dialog, this value will be the number of files selected by 
the user. 


usDIgID (USHORT) 
Custom dialog ID. 


The ID of the dialog window. When FDS_CUSTOM is set, this field contains the ID of 
the resource containing the custom dialog template. 


x (SHORT) 
X-axis dialog position. 


This, along with y and hwndP, is used to position the dialog. It is updated in the 
structure if the user moves the dialog to a new position. If the FILEDLG structure is 
reused, the dialog appears in the position at which it was left each time it is invoked. 
The FDS_CENTER flag overrides this position and automatically centers the dialog in its 
parent. 


y (SHORT) 
Y-axis dialog position. 


This, along with x and hwndP, is used to position the dialog. It is updated in the 
structure if the user moves the dialog to a new position. If the FILEDLG structure is 
reused, the dialog appears in the position at which it was left each time it is invoked. 
The FDS_CENTER flag overrides this position and automatically centers the dialog in its 
parent. 


SEAType (SHORT) 
Selected extended-attribute type. 


Returns a selected extended-attribute type to assign to the file name returned in 
szFullFile. This field is a zero-based offset into the papsz/TypeList and is returned only 
when the Save As dialog is used. A -1 value is returned when the Open dialog is used. 


FIXED 


Signed-integer fraction (16:16). This can be treated as a LONG where the value has been 
multiplied by 65 536. 


Syntax 
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FONTDLG 


Font-dialog structure. 


Syntax 


r 


Fields 
cbSize (ULONG) 
Structure size. 


This field allows for future expansion of the structure, and must be initialized with the 
size of the FONTDLG structure. 
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hpsScreen (HPS) 
Screen presentation space. 


If not NULLHANDLE, the screen presentation space from which screen fonts are 
queried. 


hpsPrinter (HPS) 

Printer presentation space. 

If not NULLHANDLE, the printer presentation space from which printer font are queried. 
pszTitle (PSZ) 

Dialog title string. 

Application-provided dialog title. If NULL, it defaults to “Font.” 
pszPreview (PSZ) 

Font-preview window string. 

String to show in font-preview window. If NULL, it defaults to “abcdABCD.” 

Note: Care is necessary when choosing the string to put in this field. Using many 

different characters causes excess memory to be used by the font cache. 
pszPtSizeList (PSZ) 

Application-provided point size list. 


String which contains a list of point sizes to be used as the default list for outline fonts in 
the point-size drop-down area. Point sizes are separated by spaces. If NULL, the point 
size drop down defaults to 8, 10, 12, 14, 18, and 24. 


pfnDigProc (PFNWP) 
Custom dialog procedure. 


NULL unless the caller is subclassing the font dialog. When non-NULL, it points to the 
dialog procedure of the application. 


pszFamilyname (PSZ) 
Family name buffer. 


Buffer provided by the application for passing the family name of the font. The font 
family name used by the application to select a font. When the first character in this 
string is NULL, no family name was initially selected, and the dialog defaults to the 
system font. 


A buffer must be passed to the font dialog to allow the dialog to return the selected font 
family name. The size of this buffer is placed in the usFamilyBufLen field. 

fxPointSize (FIXED) 
Point size of the font. 
lf FNTS_OWNERDRAWPREVIEW is set, 0 means the user wants to leave the font size 
unchanged and the application must update the preview area. 


fl (ULONG) 
FNTS _* flags. 
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FNTS_APPLYBUTTON 


FNTS_BITMAPONLY 
FNTS_CENTER 
FNTS CUSTOM 


FNTS_FIXEDWIDTHONLY 


FNTS_HELPBUTTON 


FNTS_INITFROMFATTRS 


FNTS_MODELESS 


FNTS_NOSYNTHESIZEDFONTS 
FNTS_OWNERDRAWPREVIEW 


FNTS_PROPORTIONALONLY 


FNTS_RESETBUTTON 


-FNTS_VECTORONLY 


flFlags (ULONG) 


FNTF_* flags. 
FNTF_NOVIEWPRINTERFONTS 
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- An Apply push button is added to the dialog. This 


is useful in a modeless dialog. 

The dialog presents bit-map fonts only. An 
application that changes fonts by using the 
presentation parameters (PP_* values) could use © 


’ this flag. 


The dialog is positioned in the center of its parent 
window, overriding any specified x,y position. 

A custom dialog template is used to create the 
dialog. The hMod and usDigld fields must be 
initialized. 

The dialog presents fixed-width (monospace) fonts 
only. 

A Help push button of style 
(BS_HELP|BS_NOPOINTERFOCUS) with an ID of 
DID_HELP_BUTTON is added to the dialog. If the 
push button is pressed, a WM_HELP message is 
sent to the hwndO parameter of the WinFontDlg 
function call. 

The dialog initializes itself from the font attribute 
structure (FATTRS) that is passed. 

The dialog is modeless; WinFontDlg returns 
immediately after creating the dialog window and 
returns the window handle to the application. The 
application should treat the dialog as if it were 
created with WinLoadDlg. As in the modal (default) 
dialog case, the return value is found in the /Return 
field of the FONTDLG structure passed to 
WinFontDlg. 

The dialog does not synthesize any fonts. 

This flag makes the check boxes in the font dialog 
three-state check boxes, enabling the user to leave 
certain style attributes unchanged. Additionally, a 
WM_DRAWITEM message will be sent to the 
owner, providing the owner an opportunity to draw 
the preview window itself. 

The dialog presents proportionally spaced fonts 
only. 

A Reset push button is added to the dialog. When 
this push button is pressed, the values for the 
dialog are restored to their initial values. 

The dialog presents vector fonts only. 


This flag is initialized only when both hpsScreen 
and hpsPrinter are not NULLHANDLE. On input, 
this parameter determines whether the printer fonts 


are to be included in the font list box. The user 
controls this with a check box. 
FNTF_NOVIEWSCREENFONTS 


This flag is initialized only when both hpsScreen 
and hpsPrinter are not NULLHANDLE. On input, 
this parameter determines whether the screen 
fonts should be included in the font list box. The 
user controls this with a check box. 

FNTF_PRINTERFONTSELECTED _ This determines if a printer-specific font is selected 
by the user. The application should make an 
approximation of this printer font when outputting 
to the screen. This is an output-only flag and is 
ignored on input. 

FNTF_SCREENFONTSELECTED _ This determines if a screen-specific font is selected 
by the user. The application should make an 
approximation of this screen font when outputting 
to the screen. This is an output-only flag and is 
ignored on input. 


flType (ULONG) 
The selected type bits. 


These flags specify what additional attributes the user specified for the font. This field is 
used as the #lOptions field in the FACENAMEDESC structure for GpiQueryFaceString. 


flTypeMask (ULONG) 
Mask of type bits to use. 


This field is used only if FNTS_OWNERDRAWPREVIEW is specified. It tells which flags. 
of the f!TypeMask field the user wants to change, and is relevant only if the text for 
which the font is selected has different faces and styles. 


flStyle (ULONG) 
Selected style bits. 


Flags for any additional selections the user specified for the font. This field is used as 
the fsSelection field in the FATTRS structure passed to GpiCreateLogFont. 


flStyleMask (ULONG) 
Mask of style bits to use. 
This field is used only if FNTS_OWNERDRAWPREVIEW is specified. It tells which flags 


of the flStyle field the user wants to change and is relevant only if the text for which the 
font is selected has different faces and styles. 


clrFore (LONG) 
Font foreground color. 


Foreground color of the font. This color is a value used for the color mode that 
hpsScreen is in. lf FNTS_OWNERDRAWPREVIEW is specified, this value can be 
CLR_NOINDEX, leaving the foreground color “as is.” 
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_ clrBack (LONG) 
Font background color. 


Background color of the font. This color is a value used for the color mode that 
hpsScreen is in. lf FNTS_OWNERDRAWPREVIEW is specified, this value can be 
CLR_NOINDEX leaving the background color “as is.” | 


ulUser (ULONG) 
Application-defined. 


A ULONG that an application uses to store its state information when it is subclassing 
the font dialog. 


IReturn (LONG) 
Return value. 


Return value from WinFontDig. This value is the ID of the push button pressed to | 
dismiss the dialog, DID_OK or DID_CANCEL, unless the application supplied additional 
push buttons in its template. 


ISRC (LONG) 
System return code. 


This field contains an FNTS_ERR return code. When a dialog fails, this field is used to 
tell the application the reason for the failure. 


lEmHeight (LONG) 
Em height. 


The Em height of the current font. This is the same as in the FONTMETRICS structure. 
It is an output-only parameter and its value has no effect on the behavior of the font 
dialog, but is updated when the user dismisses the dialog. 


IXHeight (LONG) 
X height. 
The x height of the current font. This is the same as in the FONTMETRICS structure. It 
is an output-only parameter and its value has no effect on the behavior of the font 
dialog, but is updated when the user dismisses the dialog. 


lExternalLeading (LONG) 
External leading. 


The external leading of the font. This is the same as in the FONTMETRICS structure. It 
is an output-only parameter and its value has no effect on the behavior of the font 
dialog, but is updated when the user dismisses the dialog. 


hMod (HMODULE) 
Module for custom dialog resources. 


lf FNTS_CUSTOM is set, this is the HMODULE from which the custom font dialog 
template is loaded. NULLHANDLE causes the dialog resource to be pulled from the 
module of the current EXE. , 
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fAttrs (FATTRS) 
Font-attribute structure. 


Font-attribute structure of selected font. The FATTRS for the selected font. This is 
output-only for all fields except usCodePage, which is input/output, and the initial code 
page value passed is used for font selection. The value returned is the one for the 
matching font. 


sNominalPointSize (SHORT) 
Font point size. 


The nominal point size of the font. This is the same as in the FONTMETRICS structure. 
It is an output-only parameter and its value has no effect on the behavior of the font 
dialog, but is updated when the user dismisses the dialog. 


usWeight (USHORT) 
Font weight. 


The weight of the font. This is the weight-class/boldness the user selects for the font. 
This field is used as the usWeightClass field in the FACENAMEDESC structure for 
GpiQueryFaceString. When FNTS_-OWNERDRAWPREVIEW is set, 0 causes the 
application to leave the font weight “as is” and the application must update the preview 
area. 


usWidth (USHORT) 
Font width. 


The width of the font. This is the width-class the user selects for the font. This field is 
used as the usWidthClass field in the FACENAMEDESC structure for 
GpiQueryFaceString. When FNTS_OWNERDRAWPREVIEW is set, 0 causes the 
application to leave the font width “as is” and the application must update the preview 
area. . 


xX (SHORT) 
The x-axis dialog position. 


This, along with y and hwndP, is used to position the dialog. It is updated in the 
structure if the user moves the dialog to a new position. This way, the dialog appears in 
the position at which it was left each time it is invoked. The FNTS_CENTER flag 
overrides this position and automatically centers the dialog in its parent. 


y (SHORT) 
The y-axis dialog position. 


This, along with x and hwndP, is used to position the dialog. It is updated in the 
structure if the user moves the dialog to a new position. This way, the dialog appears in 
the position at which it was left each time it is invoked. The FNTS_CENTER flag 
overrides this position and automatically centers the dialog in its parent. 


usDigid (USHORT) 
Dialog ID. 


This sets the ID of the dialog window. If FNTS_CUSTOM is set, this is the ID of the 
resource that contains the custom dialog template. 
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usFamilyBufLen (USHORT) 
Buffersize. 


Size of the buffer passed in the pszFamilyname resource that contains the custom 
dialog template. 


usReserved (USHORT) 
Reserved. 


This is a reserved field. 


FONTMETRICS 


Font-metrics structure. 


This structure is returned to applications on the GpiQueryFonts and GpiQueryFontMetrics 
calls and conveys information from the font creator to the application. 


Syntax 
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typedef PN ae 
_ CHAR . 
CHAR 
 USHORT. 
USHORT isCodePage: 
ene ee 


_ USHORT 
USHORT 

- SHORT 

SHORT = 

SHORT 
SHORT 
SHORT 
SHORT 

SHORT 


Sor we 
“SHORT 
—USHORT 
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Fields 
szFamilyName[FACESIZE] (CHAR) 
Family name. 


The family name of the font that describes the basic appearance of the font, for 
example, Times New Roman* This string is null terminated, and therefore is limited to 
31 characters in length. Longer names may be retrieved by using the FamilyNameAtom 
field to retrieve the full name from the System Atom table. 


szFaceName[FACESIZE] (CHAR) 
Face name. 


The typeface name that defines the particular font, for example, Times New Roman Bold 
Italic. This string is null terminated, and therefore is limited to 31 characters in length. 

' Longer names may be retrieved by using the FaceNameAtom field to retrieve the full 
name from the System Atom table. 


idRegistry (USHORT) 
Registry identifier. 


The IBM registered number (or zero). 


usCodePage (USHORT) 
Code page. 


Defines the registered code page supported by the font. For example, the original IBM 
PC code page is 437. A value of 0 implies that the font may be used with any of the 
OS/2 supported code pages. 


Where a font contains special symbols for which there is no registered code page, then 
code page 65400 is used. 


lEmHeight (LONG) 
Em height. 


The height of the Em square in world coordinate units. This corresponds to the point 
size for the font. 


IXHeight (LONG) 
X height. 


The nominal height above the baseline for lowercase characters (ignoring ascenders) in 
world coordinate units. 


IMaxAscender (LONG) 
Maximum ascender. 


The maximum height above the baseline reached by any part of any symbol in the font 
in world coordinate units. This field may exceed /EmHeight. 


IMaxDescender (LONG) 
Maximum descender. 


The maximum depth below the baseline reached by any part of any Syne in the font in 
world coordinate units. This field may exceed /EmHeight. 
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lILowerCaseAscent (LONG) 
Lowercase ascent. 


The maximum height above the baseline reached by any part of any lowercase (Latin 


unaccented “a” through “z”) symbol in the font in world coordinate units. 


lLowerCaseDescent (LONG) 
Lowercase descent. 


The maximum depth below the baseline reached by any part of any lowercase (Latin 
unaccented “a” through “z”) symbol in the font in world coordinate units. 


lInternalLeading (LONG) 
Internal leading. 


The amount of space which, when subtracted from /MaxAscender, gives a font-design 
dependent, but glyph-set independent, measure of the distance above the baseline that 
characters extend. This calculation approximates the visual top to a row of characters 
without actually looking at the characters in the row. 


For optimum results, this field should be used by applications to position the first line of 
a block of text by subtracting it from /MaxAscender and positioning the baseline that 
distance below whatever is above the text. 


Note: This does not guarantee that characters will not overwrite information above 
them, but does give a font designer's view of where to place the text. Collision 
should be tested for, and additional space allocated if necessary. 


lExternalLeading (LONG) 
External leading. 


The amount of guaranteed white space advised by the font designer to appear between: 
adjacent rows of text. This value may be zero. 


Note: The fonts built in to Presentation Manager have zero in this field. 


IAveCharWidth (LONG) 
Average character width. 


This is determined by multiplying the width of each lowercase character by a constant, 
adding the products, and then dividing by 1000. The letters involved in this, plus their 
constants, are as follows: 


Constant 
64 
14 
27 
35 
100 
20 
14 
42 
63 
3 

6 


- 
cy) 
= 
® 
= 


To *~@oa 0 07 


xo 
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Note: For fixed pitch fonts, this value will be the same as the (A width + B width + C 
width) escapement of each character. 


IMaxCharlInc (LONG) 
Maximum character increment. 


The maximum character increment for the font in world coordinate units. 


lEminc (LONG) 
Em increment. 


The width of the Em square in world coordinate units. This corresponds to the point size 
of the font. When the horizontal device resolution equals the vertical device resolution 
this is equal to the em height. 


IMaxBaselineExt (LONG) 
Maximum baseline extent. 


The maximum vertical space occupied by the font, in world coordinate units. This is the 
sum of [MaxAscender and IMaxDescender if both are positive. It is also the sum of 
linternalLeading and l[EmHeight. 


One possible type of line spacing can be computed by adding /MaxBaselineExt to 
[ExternalLeading. Such a line spacing, however, would be dependent on the glyph set 
included in the font. If a new version of the font should be made available, with new 
glyphs, then it is possible that this value will change because one of the new glyphs has 
gone above the previous /MaxAscender or below the previous /MaxDescender. More 
sophisticated applications will base line spacing on the point size (/EmHeight) of the font, 
which is an invariant of the font, multiplied by some factor (for example, 120%) plus any 
external leading. 


This field may’ exceed /EmHeight. 


sCharSlope (SHORT) 
Character slope. 


Defines the nominal slope for the characters of a font. The slope is defined in degrees 
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increasing clockwise from the vertical. An italic font is an example of a font with a 
nonzero slope. 


Note: The units for this metric are degrees and minutes, encoded as shown in the 
following example: 


180 degrees 59 minutes would be represented as : 
< byte 1 > < byte 2 > | 
| 

< Minutes > | 
| 

| 

| 

59 min | 


sInlineDir (SHORT) 
Inline direction. 


180 degrees 


The direction in which the characters in the font are designed for viewing. The direction 
is defined in degrees increasing clockwise from the horizontal (left-to-right). Characters 
are added to a line of text in the inline direction. 


Note: The units for this metric are degrees and minutes, encoded as shown in 
sCharSlope. 


sCharRot (SHORT) 
Character rotation. 


The rotation of the character glyphs with respect to the baseline, the angle increasing 
counter clockwise. This is the angle assigned by the font designer. 


Note: The units for this metric are degrees and minutes, encoded as shown in 
sCharSlope. 


usWeightClass (USHORT) 
Weight class. 


Indicates the visual weight (thickness of strokes) of the characters in the font: 


Value Description 
Ultra-light 


Extra-light 

Light 

Semi-light 
Medium (normal) 
Semi-bold 

Bold 

Extra-bold 
Ultra-bold 


usWidthClass (USHORT) 
Width class. 


Indicates the relative aspect ratio of the characters of the font in relation to the normal 
aspect ratio for this type of font: 


OON DOA PWND — 
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Value Description % of normal width 
1 Ultra-condensed 50 : 

2 Extra-condensed 62.5 

3 Condensed 75 

4 Semi-condensed 87.5 

5 Medium (normal) 100 

6 Semi-expanded 112.5 

7 Expanded : 125 

8 ' Extra-expanded 150 

9 Ultra-expanded 200 


sXDeviceRes (SHORT) 
X-device resolution. 


For bit-map fonts this is the resolution in the X direction of the intended target device, 
measured in pels per inch. 


For outline fonts this is the number of notional units in the X direction of the Em square, 
measured in notional units per Em. (Notional units are the units in which the outline is 
defined.) 


sYDeviceRes (SHORT) 
Y-device resolution. 


For bit-map fonts this is the resolution in the Y direction of the intended target device, 
measured in pels per inch. 


For outline fonts this is the number of notional units in the Y direction of the Em square, 
measured in notional units per Em. (Notional units are the units in which the outline is 
defined.) 


sFirstChar (SHORT) 
First character. 


The code point of the first character in the font. 


sLastChar (SHORT) 
Last character. 


The code point of the last character in the font, expressed as an offset from sFirstChar. 


All code points between the first and last character specified must be supported by the 
font. 


sDefaultChar (SHORT) 
Default character. 


The code point that is used if a code point outside the range supported by the font is 
used, expressed as an offset from sFirstChar. 


sBreakChar (SHORT) 
Break character. 


The code point that represents the “space” or “break” character for this font, expressed 
as an offset from sFirstChar. For example, if the first character is the space in code 
page 850, sFirstChar = 32, and sBreakChar = 0. 
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sNominalPointSize (SHORT) 
Nominal point size. 


For a bit-map font, this field contains the height of the font. 


For an outline font, this field contains the height intended by the font designer. For 
example, some fonts are designed for text use in which case a value of 120 (12 point) 
would probably be placed in this field, whereas other fonts are designed for “display” use 
(“display” is typographer’s terminology for larger sizes). This is not the only size at 
which the font can be used. 


Measured in decipoints (a decipoint is 1/720th of an inch). 


sMinimumPointSize (SHORT) 
Minimum point size. 


For a bit-map font, this field does not apply. For an outline font, this field contains the 
minimum height intended by the font designer. Note that this is not a restriction of the 
size at which the font can be used. 


Measured in decipoints (a decipoint is 1/720th of an inch). 


sMaximumPointSize (SHORT) 
Maximum point size. 


For a bit-map font, this field does not apply. 


For an outline font, this field contains the maximum height intended by the font designer. 
Note that this is not a restriction of the size at which the font can be used. 


Measured in decipoints (a decipoint is 1/720th of an inch). 


fsType (USHORT) 
Type indicators. 


Contains this information: 


FM_TYPE_FIXED Characters in the font have the same fixed width. 
FM_TYPE_LICENSED Licensed (protected) font. 

FM_TYPE_KERNING Font contains kerning information. 

FM_TYPE_64K Font is larger than 64KB (KB equals 1024 bytes) in size. If 


the following two bits are false, the font is for single-byte 
code pages. One of the bits may be set. 
FM_TYPE_DBCS Font is for double-byte code pages. 
FM_TYPE_MBCS Font is for mixed single- or double-byte code pages. 
FM_TYPE_FACETRUNC _ Font szFaceName has been truncated. 
FM_TYPE_FAMTRUNC Font szFamilyName has been truncated. 
FM_TYPE_ATOMS The System Atom table atom values in FamilyNameAtom 
and in FaceNameAtom are valid. 


fsDefn (USHORT) 
Definition indicators. 


Contains the following font definition data: 


FM_DEFN_OUTLINE — Font is a vector (outline) font; otherwise, it is a bit-map font. 
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FM_DEFN_GENERIC Font is in a format that can be used by the GPI; otherwise, it is 
a device font. . 


fsSelection (USHORT) 
Selection indicators. 


‘Contains information about the font patterns in the physical font. 


Note: The flags do not reflect simulations applied to the physical font. 


Possible values are: 


FM_SEL_ITALIC 
FM_SEL_UNDERSCORE 


FM_SEL_NEGATIVE 
FM_SEL_OUTLINE 
FM_SEL_STRIKEOUT 
FM_SEL_BOLD 


FM_SEL_1S09241_ TESTED 


fsCapabilities (USHORT) 
Capabilities. 


True indicates that this font is designed as an italic font. 
TRUE indicates that this font is designed with 
underscores included in each character. 

TRUE indicates that this font is designed with the 
background and foreground reversed. 

TRUE indicates that this font is designed with outline 
(hollow) characters. 

TRUE indicates that this font is designed with an 
overstrike through each character. 

TRUE indicates that this font is designed with bold 
characters. 

This flag indicates that the font has been tested for 
compliance to ISO 9241. The presence of this flag 
doesn't indicate whether the font passed or failed, only 
that it was tested. 


Note: While the fonts were primarily tested for meeting 
the ISO standard, they have also been designed 
to meet the German standard DIN 66 234. 
Where the two standards differ, the fonts have 
been designed to meet the more stringent 
requirement. 


This attribute applies only to device fonts. 


FM_CAP_NOMIX Characters may not be mixed with graphics. 


QUALITY The most significant byte may contain the following numeric value: 
0 Undefined 
1 DP quality 
2 DP draft 
3 Near Letter Quality 
4 


ISubscriptXSize (LONG) 
Subscript x-size. 


Letter Quality 


The horizontal size recommended by the font designer for subscripts for this font in 


world coordinate units. 
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ISubscriptYSize (LONG) 
Subscript y-size. 


The vertical size recommended by the font designer for subscripts for this font in world 
coordinate units. 


ISubscriptXOffset (LONG) 
Subscript x-offset. 


The baseline x-offset recommended by the font designer for subscripts for this font in 
world coordinate units. 


ISubscriptYOffset (LONG) 
Subscript y-offset. 


The baseline y-offset recommended by the font designer for subscripts for this font in 
world coordinate units. 


Note: Positive numbers indicate an offset below the baseline. 


ISuperscriptXSize (LONG) 
Superscript x-size. 


The horizontal size recommended by the font designer for superscripts for this font in 
world coordinate units. 


' [SuperscriptYSize (LONG) 

Superscript y-size. 

The vertical point size recommended by the font designer for superscripts for this font in 
world coordinate units. 


ISuperscriptXOffset (LONG) 
Superscript x-offset. 


The baseline x-offset recommended by the font designer for superscripts for this font in 
world coordinate units. 


ISuperscriptYOffset (LONG) 
Superscript y-offset. 


The baseline y-offset recommended by the font designer for superscripts for this font in 
world coordinate units. 


lUnderscoreSize (LONG) 
Underscore size. 


The width (thickness) of the underscore stroke in world coordinate units. This describes 
the actual underscore in the font if FM_SEL_UNDERSCORE is also set. Otherwise it 
describes what the engine will simulate if underscore is requested in GpiCreateLogFont. 


IUnderscorePosition (LONG) 
Underscore position. 


The position of the underscore stroke from the baseline in world coordinate units. This 
describes the actual underscore in the font if FM_SEL_UNDERSCORE is also set. 
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Otherwise it describes what the engine will simulate if underscore is requested in 
GpiCreateLogFont. 


Note: Positive values indicate an offset below the baseline. 


IStrikeoutSize (LONG) 
Strikeout size. 


The width of the strikeout stroke in world coordinate units. This describes the actual 
underscore in the font if FM_SEL_STRIKEOUT is also set. Otherwise it describes what 
the engine will simulate if overstrike is requested in GpiCreateLogFont. 


IStrikeoutPosition (LONG) 
Strikeout position. 


The position of the strikeout stroke relative to the baseline in world coordinate units. 
This describes the actual underscore in the font if FM SEL STRIKEOUT is also set. 
Otherwise it describes what the engine will simulate if overstrike is requested in 
GpiCreateLogFont. 


sKerningPairs (SHORT) 
Kerning pairs. 


The number of kerning pairs in the kerning pair table. 


sFamilyClass (SHORT) 
Font family design classification. 


This value contains a font class and its subclass. 


IMatch (LONG) 
Matched font identity. 


This uniquely identifies the font for a given device and device driver combination. A 
positive match number signifies that the font is a generic (engine) font while a negative 

. number indicates a device font (a native or downloadable font). This value should not 
be used to identify a font across system boundaries. 


FamilyNameAtom (LONG) 
Font family name atom. 


This value contains the atom identifier for the font family name in the System Atom 
Table. 


FaceNameAtom (LONG) 
Font facename atom. 


This value contains the atom identifier for the font face name in the System Atom Table. 


panose (PANOSE) 
Panose font descriptor. 


This is the Panose descriptor identifying the visual characteristics of the font. 
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FRAMECDATA 


Frame-control data structure. 


Syntax 


typedef struct FRAMECDATA { 
USHORT cb; 
ULONG flCreateFlags: 
USHORT hmodResources; 
USHORT idResources; 

}: FRAMECDATA; 


typedef FRAMECDATA *PFRAMECDATA; 


Fields 
cb (USHORT) 
Length. 


flCreateFlags (ULONG) 
Frame-creation flags. 


Possible values are described in the following list: 


FCF_TITLEBAR 
FCF_SYSMENU 
FCF_MENU 
FCF_SIZEBORDER 
FCF_MINBUTTON 
FCF_MAXBUTTON 
FCF_MINMAX 
FCF_VERTSCROLL 
FCF_HORZSCROLL 
FCF_DLGBORDER 
FCF_BORDER 
FCF_SHELLPOSITION 
FCF_TASKLIST 
FCF_NOBYTEALIGN 
FCF_NOMOVEWITHOWNER 
FCF_ICON 
FCF_ACCELTABLE 
FCF_SYSMODAL 
FCF_SCREENALIGN 
FCF_MOUSEALIGN 
FCF_HIDEBUTTON 
FCF_HIDEMAX 
FCF_AUTOICON 
FCF_DBE_APPSTAT 
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FCF_STANDARD The standard setting is equivalent to setting 
FCF_TITLEBAR, FCF_SYSMENU, FCF_MENU, ~ 
FCF_SIZEBORDER, FCF_MINMAX, FCF_ICON, 
FCF_ACCELTABLE, FCF_SHELLPOSITION, and 
FCF_TASKLIST. : 


hmodResources (USHORT) 
Identifier of required resource. } 


This is supplied in an environment-dependent manner. 


idResources (USHORT) 
Resource identifier. 


GRADIENTL 


Direction-vector structure. 


Syntax 


TL *PGRADTENTL 


Fields 
x (LONG) . 
X-component of direction. 


y (LONG) 
Y-component of direction. 


HAB 
Anchor-block handle. 


Syntax 
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HACCEL 


Accelerator-table handle. 


Syntax 


typedef LHANDLE HACCEL; 


HAPP 


Handle of an application. 


Syntax 


typedef LHANDLE HAPP; 


HATOMTBL 


Atom-table handle. 


Syntax 


typedef LHANDLE HATOMTBL; 


HBITMAP 
Bit-map handle. 


Syntax 


| typedef LHANDLE HBITMAP; 
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HDC 


Device-context handle. 


Syntax 


HCINFO . 


Hardcopy-capabilities structure. 


Syntax 


Fields 
szFormname[32] (CHAR) 
Form name. 


cx (LONG) 
Width (left-to-right) in millimeters. 


cy (LONG) 
Height (top-to-bottom) in millimeters. 


xLeftClip (LONG) 
Left clip limit in millimeters. 


yBottomClip (LONG) 
Bottom clip limit in millimeters. 


xRightClip (LONG) 
Right clip limit in millimeters. ; 
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yTopClip (LONG) 
Top clip limit in millimeters. 


xPels (LONG) 
Number of pels between left and right clip limits. 


yPels (LONG) 
Number of pels between bottom and top clip limits. 


flAttributes (LONG) 
Attributes of the form identifier. 


HCAPS_ SELECTABLE _ The form is installed on the printer as given by the printer 
properties dialog. It is available from an alternate form source 
without operator intervention. If the form does not have this 
bit set, and is used (if the user selects it), a “forms mismatch” 
error is generated by the printer object. 

HCAPS_CURRENT The form is the one currently selected by the DevOpenDC 
DEVOPENSTRUC pariv field (the job properties). 


HDDF 


Dynamic data formatting handle. 


Syntax 
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HELPINIT 


Help Manager initialization structure. 


Syntax 


el ihe 
 fShowPanelld; 


Fields 
cb (ULONG) 
Count of bytes of the initialization structure. 


ulReturnCode (ULONG) 
Value returned by the Help Manager from initialization. 


‘0 Initialization was successful. 


pszTutorialName (PSZ) 
Indicates to the Help Manager that the application has a tutorial program. 


NULL The application either does not have a tutorial program, or the tutorial name is 
specified in each help panel definition. 


Other Default tutorial name. 


htHelpTable (HELPTABLE) 
Help table. 


The help table or the identity of the help table. If this is the identity of the help table ina 
resource file, the low-order word contains the identity of the table and the high-order 
word must be OxFFFF. 


The help table associates each application window with its help subtable. and the identity 
of its extended help panel. 
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hmodHelpTableModule (HMODULE) 
Resource file identity. 


If the htHelpTable contains the identity of the help table, this field identifies the module 
handle returned by the DosLoadModule call by which the application loaded the 
~ resource file. 


NULL The resource file containing the help table was appended to the application’s 
.EXE file. 


Other Resource file identity. 


hmodAccelActionBarModule (HMODULE) 
Handle of the containing DLL. 


The handle of the DLL which contains the accelerator table and action bar template to 
be used by the Help Manager. 


NULL Use the default action bar and accelerator table defined by the Help Manager. 
Other Handle of the DLL. 


idAccelTable (ULONG) 
Identity of the accelerator table. 


The accelerator table resides in the DLL provided in the hmodAccelActionBarMoadule 
field. 


NULL Use the default accelerator table. 
Other Identity of the accelerator table. 


idActionBar (ULONG) 
Identity of the action bar template used by the Help Manager. 


The action bar template resides in the DLL provided in the hmodAccelActionBarModule 
field. 


NULL Use the default action bar. 
Other Identity of the action bar. 


pszHelpWindowTitle (PSZ) 
Window title for the main help window of this help instance. 


fShowPanelld (ULONG) 
Show panel identity indicator. 


The constants corresponding to the panel identity flags are in the PMHELP.H include 
file. 


CMIC_SHOW_PANEL_ID Show the. panel identity on a help panel. 
CMIC_HIDE_PANEL_ID Do not show the panel identity on a help panel. 


Appendix A. Data Types A-105 


pszHelpLibraryName (PSZ) 
Help panel library names. 


The names of the help panel libraries that the Help Manager searches on each help 
request. The names must be separated by a blank. 


The Help Manager looks for the libraries in the path set by the HELP environment 
variable. If the library is not found, the Help Manager will look for the libraries in the 
current directory. 


HELPSUBTABLE 
Help subtabie. 


A help subtable is an array of records, preceded by a value that specifies the size of each 
help-subtable record. 


Syntax 


typedef USHORT _HELPSUBTABLE { 
USHORT usSubitemSize; 


_USHORT vee Hel publablebnery()s 
a HELPSUBTABLE; 


The first entry in the help subtable indicates the size of the records that follow in the 
subtable. Each of the following entries in the help subtable is a record that consists of a 
Field ID parameter, a Help Panel ID parameter, and an optional array of application-related 
USHORT integers. The minimum number of words in the record is two: the Field 1D and the 
Help Panel ID. The last record in the subtable must be a NULL entry. 


The Field ID is the symbolic constant for a field from which the user can request help. The 
Field ID can identify a control, a menu item, or a message box, and must be unique across 
the help subtable. The value OxFFFF is reserved for use by the Help Manager. 


The Help Panel ID is the resource ID (res) of the contextual help panel to be associated with 
the field in the Field ID parameter. This is the panel to be displayed when the user requests 
help for the field. 


The optional array of USHORT integers is ignored by the Help Manager and can be used to 
store information of relevance to the application. 


There can be a maximum of 16,000 help subtables for a given help instance and each 
subtable can have a maximum of 64K bytes of data. 
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The following figure contains the declaration of a help subtable that contains only Field IDs 
and Help Panel IDs. In this subtable, each of the records after the size entry consists of 1 
Field ID and 1 Help Panel ID for a size of 2. Note that the last record is filled with NULLs (0) 


to indicate the end of the array. 
HELPSUBTABLE HelpSubTable[] = 


Fields 


usSubitemSize (USHORT) 


IDRES_HELP1, 
IDRES HELP2, 
IDRES _HELP3, 
IDRES_HELP4, 
IDRES_HELP5, 
IDRES HELP6, 


Size of each record */ 


The 
The 
The 
The 
The 
The 


first record 
second record 
third record 
fourth record 
fifth record 
sixth record 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


NULL record == end of the array */ 


Size of each record of the help subtable. 


This entry defines the number of parameters in each record in the rest of the help 
subtable. The minimum number of words in each record is two. 


2 


Other 


HelpSubTableEntry[] (USHORT) 


Help subtable records. 


The minimum number of words in each record of the help subtable. This value 
is used when each help subtable record consists only of a Field ID and Help 

Panel ID. 
This value is used when a help subtable record consists of a Field ID, Help 
Panel ID, and an array of application-related USHORT integers. 


This is the array of help subtable records, each of which contains a Field ID, a Help 
Panel ID, and an optional array of application-related USHORT integers. The last record 
of the array must be a NULL entry. 
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HELPTABLE 
Help table. 


This is a collection of help table entries, each of which has the structure defined below, the 
last entry of the collection being a NULL structure. 


Syntax 


Fields 
idAppWindow (USHORT) 
Application window identity. 


phstHelpSubTable (PHELPSUBTABLE) 
Help subtable for this application window. 


idExtPanel (USHORT) 
Identity of the extended help panel for the application window. 


HENUM 


Window-enumeration handle. 


Syntax 


HEV 


32-bit value used as an event semaphore handle. 


Syntax 
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HINI 


Initialization-file handle. 


Syntax 


-_ typed 


HLIB 
Library handle. 


Syntax 


“typedef HMODULE HLIB; 


HMF 
Metafile handle. 


Syntax 


HMODULE 
Module handle. 


Syntax 
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HMQ 


Message-queue handle. 


- Syntax 


HMTX 


32-bit value used as a mutex semaphore handle. 


Syntax 


HMUX 


32-bit value used as a muxwait semaphore handle. 


Syntax 


HOBJECT 


Workplace object handle. 


Syntax 
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HPOINTER 


Pointer handle. 


Syntax 


_ typedef LHANDLE HPOINTER; 


HPROGRAM 


Program handle. 


Syntax 


typedef LHANDLE HPROGRAM; 


HPS 


Presentation-space handle. 


Syntax 


“typedef LHANDLE HPS; 


HRGN 


Region handle. 


Syntax 
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HSAVEWP 


Frame window-repositioning process handle. 


Syntax 


HSEM 


Semaphore handle. 


Syntax 


HSPL 


Spooler handle. 


Syntax 


HSTR 
String handle. 


Syntax 
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HSWITCH 
Switch-list entry handle. 


Syntax 


‘typedef LHANDLE HSWITCH; 


HWND 


Window handle. 


Syntax 


typedef LHANDLE HWND; 


ICONINFO 


Icon information data structure. 


Syntax 


_ typedef struct _ICONI 
ULONG sss ch; 
‘HMODULE =—_shmod; 

ULONG  =—sresit 


Fields 
cb (ULONG) 
Length of ICONINFO structure. 
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fFormat (ULONG) 
Indicates from where the icon resides. 


Possible values are: 


ICON_FILE Icon file supplied. 
ICON_RESOURCE __ Icon resource supplied. 
ICON_DATA Icon data supplied. 
ICON_CLEAR Go back to default icon. 


pszFileName (PSZ) 
Name of file containing icon data. 


This value is ignored if fFormat is not equal to to ICON_FILE. 


hmod (HMODULE) 
Module containing the icon resource. 


This value is ignored if fFormat is not equal to to ICON_RESOURCE. 


resid (ULONG) 
Identity of icon resource. 


This value is ignored if fFormat is not equal to to ICON RESOURCE. 


cbiconData (ULONG) 
Length of icon data in bytes. 


This value is ignored if fFormat is not equal to to ICON_DATA. 


plconData (PVOID) 
Pointer to buffer containing icon data. 


This value is ignored if fFormat is not equal to to ICON_DATA. 


IMAGEBUNDLE 


Image-attributes bundle structure. 


Syntax 
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Fields 
IColor (LONG) 
image foreground color. 


IBackColor (LONG) 
Image background color. 


usMixMode (USHORT) 
Image foreground-mix mode. 


usBackMixMode (USHORT) 
Image background-mix mode. 


IPT 


Insertion point for multi-line entry field. 


Syntax 


KERNINGPAIRS 


Kerning-pair records structure. 


Fields 
sFirstChar (SHORT) 
First character of pair. 


sSecondChar (SHORT) 
Second character of pair. 


IKerningAmount (LONG) 
Amount of kerning for this pair. 
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-LBOXINFO 


List box information structure. 


Syntax 


Fields 
litemIndex (LONG) 
Index of the item to insert after. 


Possible values are described in the following list: 


LIT ENT Add items to the end of the list. 
LIT_ SORTASCENDING Add items to the list and sort the complete list in ascending 
order. 


LIT SORTDESCENDING _ Add items to the list and sort the complete list in 
descending order. 


Other Add the items to the list after the specified zero-based 
index. Valid range is 0 to 32 767. 


ulltemCount (ULONG) 
Number of items to be inserted into the list. 


A maximum of 32768 can be inserted into the list at one time. 


reserved (ULONG) 
Reserved value, must be 0. 


reserved2 (ULONG) 
Reserved value, must be 0. 
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LHANDLE 


The handle of a resource. 


Syntax 


typedef unsigned long LHAND 


LINEBUNDLE 


Line-attributes bundle structure. 


Syntax 


“typedef struct LINEBUNDLE{ = 


usReserved; 


Fields 
iColor (LONG) 
Line foreground color. 


IBackColor (LONG) 
Line background color. 


usMixMode (USHORT) 
Line foreground-mix mode. 


usBackMixMode (USHORT) 
Line background-mix mode. 


fxWidth (FIXED) 
Line width. 


IGeomWidth (LONG) 
Geometric line width. 
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usType (USHORT) 
Line type. 


~ usEnd (USHORT) 
Line end. 


usJoin (USHORT) 
Line join. 
usReserved (USHORT) 
Reserved. 


LONG 
Signed integer in the range -2 147 483 648 through 2 147 483647. 


Syntax 


Note: Where this data type represents a graphic coordinate in world or model space, its 
value is restricted to -134 217 728 through 134 217 727. 


A graphic coordinate in device or screen coordinates is restricted to -32 768 through 
32767. 


The value of a graphic coordinate may be further restricted by any transforms 
currently in force, including the positioning of the origin of the window on the screen. 
In particular, coordinates in world or model space must not generate coordinate 
values after transformation (that is, in device or screen space) outside the range 
-32 768 through 32 767. 
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MARKERBUNDLE 


Marker-attributes bundle structure. 


Syntax 


typedef struct _MARKERBUNDLE { 
LONG 8 oe Colors: 

LONG 1BackColor; 

USHORT usMixMode; 

-USHORT usBackMixMode; ~ 
| USHORT usSet; 

- USHORT usSymbol ; 

SIZEF sizfxCell; 

} MARKERBUNDLE; 


typedef MARKERBUNDLE *PMARKERBUNDLE; 


Fields 
IColor (LONG) 
Marker foreground color. 


IBackColor (LONG) 
Marker background color. 


usMixMode (USHORT) 
Marker foreground-mix mode. 


usBackMixMode (USHORT) 
Marker background-mix mode. 


usSet (USHORT) 
Marker set. 


usSymbol (USHORT) 
Marker symbol. 


sizfxCell (SIZEF) 
Marker cell. 
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MATRIXLF 


Matrix-elements structure. 


Syntax 


Fields 
fxM11 (FIXED) 
First element of first row. 


fxM12 (FIXED) 
Second element of first row. 


IM13 (LONG) 
Third element of first row. 


fxM21 (FIXED) 
First element of second row. 


fxM22 (FIXED) 
Second element of second row. 


IM23 (LONG) 
Third element of second row. 


IM31 (LONG) — 
First element of third row. 


IM32 (LONG) 
Second element of third row. 


IM33 (LONG) 
Third element of third row. 
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MB2D 


Array of button definitions. 


Syntax 


typedef struct M820 


Fields 
achText[MAX_MB2DTEXT+1] (CHAR) 
Text of the button. 


For example, “Cancel.” 
Currently, MAX_MB2DTEXT is equal to 70. 


idButtons (ULONG) 
Button Id returned when selected. 


flStyle (ULONG) 
Button style flags. 


These style flags may be ORed with internal styles. 


MB2iINFO 


Button information block. 


Syntax 
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Fields 
cb (ULONG) 


Current size of the structure. 


hicon (HPOINTER) 
Icon handle. 


cButtons (ULONG) 
Number of buttons. 


flStyle (ULONG) 
Icon style flags. 


Possible values are described in the following list: 


MB_APPLMODAL 


MB_ERROR 


MB_ICONASTERISK 
MB_CUSTOMICON 
MB_ICONEXCLAMATION 
MB_ICONHAND 
MB_ICONQUERY 
MB_ICONQUESTION 
MB_INFORMATION 
MB_MOVEABLE 


MB_NOICON 
MB_NONMODAL 


MB_SYSTEMMODAL 
MB_WARNING 


Message box is application modal. This is the default 
case. Its owner is disabled; therefore, do not specify the 
owner as the parent if this option is used. 


Message box contains a stop sign with a white 
background. 


Message box contains a asterisk icon. 

Message box contains a custom icon specified in hicon. 
Message box contains a exclamation point icon. 
Message box contains a hand icon. 

Message box contains a question mark in a box. 
Message box contains a question mark icon. 

Message box contains a black “i” in a box. 

Message box is moveable. 


The message box is displayed with a title bar and a system 
menu, showing only the Move, Close, and Task Manager 
choices, which can be selected either by use of the 
pointing device or by accelerator keys. 


Message box does not contain an icon. 


Message box is nonmodal (the program continues after 
displaying the nonmodal message box). 


The message box remains visible until the owner window 
destroys it. Two notification messages, WM_MSGBOXINIT 
and WM_MSGBOXDISMISS, are used to support this 
non-modaility. 


Message box is system modal. 


Message box contains a black “!” in a box. 
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hwndNotify (HWND) 
Owner notification handle. 


mb2d[1] (MB2D) 
Array of button definitions. 


MENUITEM 


Menu item. 


Syntax 


typedef struct MENUITEM { 
SHORT iPosition; 
USHORT | afStyle; 
USHORT afAttribute; 
USHORT © id; 
‘HWND hwndSubMenu; 
ULONG : hitem; 

} MENUITEM; | 


typedef MENUITEM *PMENUITEM; 


Fields 
iPosition (SHORT) 
Position. 


afStyle (USHORT) 
Style. 


afAttribute (USHORT) 
Attribute. 


id (USHORT) 
Identity. 


hwndSubMenu (HWND) 
Submenu. 


hitem (ULONG) 
Item. 
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MINIRECORDCORE | 
Structure that contains information for smaller records than those defined by the 
RECORDCORE data structure. This data structure is used if the CCS_MINIRECORDCORE 
style bit is specified when a container is created. 


Syntax 


Fields 
cb (ULONG) 
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Structure size. 


The size (in bytes) of the MINIRECORDCORE structure. 
flRecordAttr (ULONG) 


Attributes of container records. 


Contains any or all of the following: 


CRA_COLLAPSED 
CRA_CURSORED 


CRA_DROPONABLE 


CRA_EXPANDED 
CRA_ FILTERED 


CRA_INUSE 


CRA_RECORDREADONLY 
CRA_SELECTED 


CRA_TARGET 


Specifies that a record is collapsed. 


Specifies that a record will be drawn with a selection 
cursor. 


Specifies that a record can be a target for direct 
manipulation. 


Specifies that a record is expanded. 


Specifies that a record is filtered, and therefore hidden 
from view. 


Specifies that a record will be drawn with in-use 
emphasis. 


Prevents a record from being edited directly. 


Specifies that a record will be drawn with selected-state 
emphasis. 


Specifies that a record will be drawn with target 


emphasis. 
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ptlicon (POINTL) 
Record position. 


Position of a container record in the icon view. 


preccNextRecord (struct_MINIRECORDCORE *) 
Pointer to the next linked record. 


pszicon (PSZ) 
Record text. 


Text for the container record. 


hptricon (HPOINTER) 
Record icon. 


Icon that is displayed for the container record. 


MLE_SEARCHDATA 


Search structure for multiline entry field. 


Syntax — 


yedef struct SEARCH { 
ORT DE 


“penReplaces 


Fields 
cb (USHORT) 
Size of structure. 


pchFind (PCHAR) 
String to search for. 


pchReplace (PCHAR) 
String to replace with. 


echFind (SHORT) | 
Length of pchFind string. 
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cchReplace (SHORT) 
Length of pchReplace string. 


iptStart (IPT) 
Point at which to start search, or point where string was found. 


Non-negative Point at which to start search. 
Negative Start search from current cursor location. 


iptStop (IPT) 
Point at which to stop search. 


Non-negative Point at which to stop search. 
Negative Stop search at end of text. 


echFound (USHORT) 
Length of string found at iptStart. 


MLEMARGSTRUCT 


Multiline entry-field margin information. 


Syntax 
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Fields 
afMargins (USHORT) 
Margin in which the event occurred. 


The left and right margins are defined as including the corners at the top and bottom, 
and the top and bottom margins are contained between them. Therefore, the corners 
are included in the sides. 


MLFMARGIN_LEFT 
MLFMARGIN_RIGHT 
MLFMARGIN_TOP 
MLFMARGIN_ BOTTOM 


usMouMsg (USHORT) 
Message identity of the original mouse event. 


iptNear (IPT) 
Insertion point nearest to the margin event. 


MLECTLDATA 


Multiline entry-field (MLE) control data structure. 


Syntax 


pedef struct -MLECTLDATA { 
Oe chelate 
pafleFormat; = 
cchlexts 


Fields 
cbCtiData (USHORT) 
Length of control data in bytes. 


aflEFormat (USHORT) 
Import/export format. 


This sets the initial import/export format. Setting this value via control data is considered 
identical to setting it through the MLM_FORMAT message. The same constants apply 
here. The default is MLE _CFTEXT. 
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cchText (ULONG) : 


Text limit. 


The maximum amount of text allowed in the MLE. This value is interpreted identically to 
the parameter of MLM _SETTEXTLIMIT. A negative value indicates that the cd is 
considered unbounded. 


iptAnchor (IPT) 


Selection anchor point. 


iptCursor (IPT) 


Selection cursor point. 


The iptAnchor and iptCursor parameters identify the beginning and ending points, 
respectively, of the selection. These values may range from 0 through the length of the 
text. The default is 0,0 and can be indicated by entering 0,0. 


cxFormat (LONG) 


Formatting-rectangle width in pels. 


cyFormat (LONG) 


Formatting-rectangle height in pels. 


The cxFormat and cyFormat parameters identify the dimensions in pels of the formatting 
rectangle, as can be set by the MLM_SETFORMATRECT message. These values are 
considered identical to the two fields in the format rectangle structure referenced in that 
message, and the interpretation of the values in these fields is governed by the 
afFormatFlags field. 


The default is the window size in both dimensions, and can be indicated by 0 values. 


afFormatFlags (ULONG) 
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Format flags. 


These flags govern the interpretation of the cxFormat and cyFormat fields, just as in the 
MLM_SETFORMATRECT message. The flag values defined there are also valid in this 
field. The default is unlimited in both directions, and is of varying size to match the 
window size. 


PM Programming Reference Vol II 


MPARAM 


4-byte message-dependent parameter structure. 


Syntax 


typedef VOID * MPARAM; 


Certain elements of information, placed into the parameters of a message, have data types 
that do not use all 4 bytes of this data type. The rules governing these cases are: 


BOOL The value is contained in the low word and the high word is 0. 
SHORT The value is contained in the low word and its sign is extended into the high 
word. 


USHORT _ The value is contained in the low word and the high word is 0. 
NULL The entire 4 bytes are 0. 


The structure of this data type depends on the message. For details, see the description of 
the particular message. 


MQINFO 


Message-queue information structure. 


‘Syntax 


Fields 
cb (ULONG) 
Length of structure. 


pid (PID) 
Process identity. 


tid (TID) 
Thread identity. 
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cmsgs (ULONG) 
Message count. 


pReserved (PVOID) 
Reserved. 


MRESULT 


4-byte message-dependent reply parameter structure. 


Certain elements of information, placed into the parameters of a message, have data types 
that do not use all 4 bytes of this data type. The rules governing these cases are: 


BOOL The value is contained in the low word and the high word is 0. 
SHORT The value is contained in the low word and its sign is extended into the high 
word. 


USHORT _ The value is contained in the low word and the high word is 0. 
NULL The entire 4 bytes are 0. 


The structure of this data type depends on the message. For details, see the description of 
the particular message. 


Syntax 


NOTIFYDELTA 


Structure that contains information about the placement of delta information for a container. 
This structure is used in the CN_QUERYDELTA container notification code only. See 
“CN_QUERYDELTA’ on page 22-27 for information about that notification code. 


Syntax 


Aypeder SUniC _NOTIFYDELTA a 
HWND = hwndCnr; ee 
ULONG eta See 
: a NOTIFYDELTA; 


: typeder | NOTIFYDELTA =*PNOTIFYD 
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Fields 
hwndCnr (HWND) 
Container contro! handle. 


fDelta (ULONG) 
Placement of delta information. The values can be: 


CMA_DELTATOP The record that represents the delta value scrolls into view at the 
; top of the client area. 

CMA_DELTABOT The record that represents the delta value scrolls into view at the 
bottom of the client area. 

CMA_DELTAHOME _ The container scrolls to the beginning of the list of all container 
records that are available to be inserted into the container, such 
as the first record in a database. 

CMA_DELTAEND The container scrolls to the end of the list of all container records 
that are available to be inserted into the container, such as the 
last record in a database. 


NOTIFYRECORDEMPHASIS 


Structure that contains information about emphasis that is being applied to a container 
record. This structure is used in the CN_EMPHASIS container notification code only. See 
“CN_EMPHASIS’” on page 22-20 for information about that notification code. 


Syntax 


typedef struct _NOTIFYRECORDEMPHASIS. { 
-HWND  hwndCnr; 
PRECORDCORE = —s pRecord; 
—ULONG fEmphasisMask; 
} NOTIFYRECORDEMPHASIS; 


typedef NOTIFYRECORDEMPHASIS *PNOTIFYRECORDEMPHASIS; 


Fields 
hwndCnr (HWND) 
Container control handle. 


pRecord (PRECORDCORE) 
Pointer to a RECORDCORE data structure whose emphasis attribute has been 
‘changed. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE 
and PMINIRECORDCORE should be used instead of PRECORDCORE in all 
applicable data structures and messages. 
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fEmphasisMask (ULONG) 
Changed emphasis attributes. 


Specifies the emphasis attribute or attributes that changed in the container record. The 
following states can be combined with a logical OR operator (|): 


¢ CRA _CURSORED 
* CRA_INUSE 
* CRA SELECTED. 


NOTIFYRECORDENTER 


Structure that contains information about the input device that is being used with the 
container control. This structure is used in the CN_ENTER container notification code only. 
See “CN_ENTER?” on page 22-22 for information about that notification code. 


Syntax 


RECORDENTER *PNOTIFYRECORDENTER 


Fields 
hwndCnr (HWND) 
’ Container control handle. 


-fKey (ULONG) 
Flag. 


Flag that determines whether the Enter key was pressed or the select button was 
double-clicked. 


TRUE The Enter key was pressed. 
FALSE _ The select button was double-clicked. 
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pRecord (PRECORDCORE) 
Pointer to the RECORDCORE data structure over which an action occurred. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE 
and PMINIRECORDCORE should be used instead of PRECORDCORE in all 
applicable data structures and messages. 


e lf auser presses the Enter key, a pointer to the record with the selection cursor is 
returned. 


* Ifa user double-clicks the select button when the pointer of the pointing device is 
over a record, a pointer to the record is returned. 


e If auser double-clicks the select button when the pointer of the pointing device is 
over white space, NULL is returned. 


NOTIFYSCROLL 
Structure that contains information about scrolling a container control window. This structure 
is used in the CN_SCROLL container notification code only. See “CN SCROLL” on 
page 22-29 for information about that notification code. 


Syntax 


Alea struct _NOTIFYSCROLL ‘ 
~HWND hwnd(nr; 
LONG - 1Scrollinc; 
-ULONG = fScroll; 
ay. NOTIFYSCROLL; 


- typecet | NOTTFYSCROLL -PuoTIFYSCROLL 4 


Fields 
hwndCnr (HWND) 
Container control handle. 


IScrolllnc (LONG) 
Scroll amount. 


Amount (in pixels) by which the window scrolled. 


fScroll (ULONG) 
Scroll flags. 


Flags that show the direction in which the window scrolled and the window that was ~ 
scrolled. 


CMA_HORIZONTAL A window was scrolled horizontally. If the split details view 
window is scrolled, a logical OR operator (|) is used to combine 
the CMA_HORIZONTAL attribute with either the CMA_LEFT 
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attribute or the CMA_RIGHT attribute to indicate which window 
was scrolled. If the unsplit details view window is scrolled, the 
CMA_HORIZONTAL attribute is combined with the CMA_LEFT 
attribute. 


CMA_VERTICAL The container window scrolled vertically. If the split details view 
; window is scrolled, a logical OR operator (|) is used to combine 
the CMA_VERTICAL attribute with the CMA_LEFT attribute and 
the CMA_RIGHT attribute. If the unsplit details view window is 
scrolled, the CMA_VERTICAL attribute is combined with the 
CMA_LEFT attribute. 


OBJCLASS 


Object class structure. 


Syntax 


Fields 
pNext (struct OBJCLASS *) 
Pointer to the next object class structure. 


pszClassName (PSZ) 
Class name. 


pszModName (PSZ) 
Module name. 
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OWNERBACKGROUND 
Structure that contains information about painting the container window’s background by the 
container owner. This structure is used in the CM_PAINTBACKGROUND container 
message only. See “CM_PAINTBACKGROUND?” on page 22-55 for information about that 
message. 


Syntax 


typedef struct _OWNERBACKGROUND {~ 
e HWND hwnd; eS 
HPS hps; 2s 
~ RECTL ——sorelBackground; 

“LONG . —s idWindow; : 

~} OWNERBACKGROUND; 


typedef OWNERBACKGROUND *POWNERBACKGROUND; 


Fields 
hwnd (HWND) 
Window handle. 


Handle of the window to be painted. 


hps (HPS) 
Presentation-space handle. 


rciBackground (RECTL) 
Background rectangle. 


Background rectangle in window coordinates. 


idWindow (LONG) 
Window ID. 


Identity of the window to be painted. 
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OWNERITEM 


Owner item. 


Syntax 


Fields 
hwnd (HWND) 
Window handle. 


hps (HPS) 
_ Presentation-space handle. 


fsState (ULONG) 
State. 


fsAttribute (ULONG) 
Attribute. 


fsStateOld (ULONG) 
Old state. 


fsAttributeOld (ULONG) 
Old attribute. 


rclitem (RECTL) 
Item rectangle. 


iditem (LONG) 
Item identity. 


hitem (ULONG) 
Item. 
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MLEOVERFLOW 


Overflow error structure for multiline entry field. 


Syntax 


typedef struct MLEOVERFLOW { 
ULONG =—_ afErrInd; 
LONG ~~ nByttesOver; 

LONG =——sépixHorzOver; 
LONG —spixVertOver; 
} MLEOVERFLOW; : 


- typedef MLEOVERFLOW *POVERFLO 


Fields 
afErrind (ULONG) 
One or more EFR_* flags. 


nBytesOver (LONG) 
Number of bytes over the limit. 


pixHorzOver (LONG) 
Number of pels over the horizontal limit. 


pixVertOver (LONG) 
Number of pels over the vertical limit. 
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PAGEINFO 


Settings page information structure. 


Syntax 


slags 


Fields 
cb (ULONG) 
Length of PAGEINFO structure. 


hwndPage (HWND) 
Handle of page. 


pfnwp (PENWP) 
Window procedure. 


resid (ULONG) 
Resource identity. 


pCreateParams (PVOID) 
Pointer to creation parameters. 


digid (USHORT) 
Dialog identity. 


usPageStyleFlags (USHORT) 
Notebook contro! page style flags. 


usPagelnsertFlags (USHORT) 
Notebook control page insertion flags. 
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usSettingsFlags (USHORT) 
Settings flag. 


This flag must be set to one of the following values: 
0 You will not get page numbers. 


SETTINGS PAGE_NUMBERS _ Page numbers will automatically be put on the status 
line for pages that have minor pages under the major 
tab page. 


If you want to use the page numbers, make sure ALL 
pages have this setting. 


pszName (PSZ) 
Pointer to a string containing page name. 


idDefaultHelpPanel (USHORT) 
Identity of default help panel. 


usReserved2 (USHORT) 
Reserved value, must be zero. 


pszHelpLibraryName (PSZ) 
Pointer to name of help file. 


pHelpSubtable (PUSHORT) 
Pointer to help subtable. 


hmodHelpSubtable (HMODULE) 
Module handle for help subtable. 


ulPageinsertid (ULONG) 
Notebook control page identity. 
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PAGESELECTNOTIFY 


Structure that contains information about the application page being selected. 


Syntax 


Fields 
hwndBook (HWND) 
Notebook window handle. 


ulPageldCur (ULONG) 
Current top page identifier. 


ulPageldNew (ULONG) 
New top page identifier. 


PANOSE 


The Panose field in the font metrics will allow for quantitative descriptions of the visual 
properties of font faces. The PANOSE definition contains ten digits, each of which currently 
describes up to sixteen variations. 


Syntax 
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Fields 
bFamilyType (BYTE) 
Family kind. 


0 Any 

1 No Fit 

2 Text and Display 
3 Script 

4 Decorative 

5 Pictorial 


bSerifStyle (BYTE) 
Serif style. 


0 Any 

1 No Fit 

2 Cove 

3 Obtuse Cove 
4 Square Cove 
5 Obtuse Square Cove 
6 Square 

7 Thin 

8 Bone 

9 Exaggerated 
10 Triangle 

11 Normal Sans 
12 Obtuse Sans 
13 Perp Sans 
14 Flared 

15 Rounded 


bWeight (BYTE) 
Weight. 


0 Any 

1 No Fit 
2 Very Light 
3 Light 

4 Thin 

5 Book 

6 Medium 
7 Demi 

8 Bold 

9 Heavy 
10 Black 
11 Nord 


Appendix A. Data Types A-141 


bProportion (BYTE) 
Proportion. 


0 Any 

1 No Fit 

2 Old Style 

3 Modern 

4 Even Width 

5 Expanded 

6 Condensed 

7 Very Expanded 
8 Very Condensed 
9 Monospaced 


bContrast (BYTE) 
Contrast. 


0 Any 

1 No Fit 

2 None 

3 Very Low 

4 Low 

5 Medium Low 
6 Medium 

7 Medium High 
8 High 

9 Very High 


bStrokeVariation (BYTE) 
Stroke Variation. 


0 Any 

1 No Fit 

2 Gradual/Diagonal 

3 Gradual/Transitional 
4 Gradual/Vertical 

5 Gradual/Horizontal 
6 Rapid/Vertical 

7 Rapid/Horizontal 

8 Instant/Vertical 


bArmStyle (BYTE) 
Arm Style. 


0 Any 

1 No Fit 

2 Straight Arms/Horizontal 

3 Straight Arms/Wedge 

4 Straight Arms/Vertical 

5 Straight Arms/Single Serif 
6 Straight Arms/Double Serif 
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7 Non-Straight Arms/Horizontal 

8 Non-Straight Arms/Wedge 

9 Non-Straight Arms/Vertical 

10 Non-Straight Arms/Single Serif 
11 Non-Straight Arms/Double Serif 


bLetterform (BYTE) 
Letterform. 


0 Any 

1 No Fit 

2 Normal/Contact 

3 ONormal/Weighted 
4 ONormal/Boxed 

5 ONormal/Flattened 
6 ONormal/Rounded 
7 ONormal/Off Center 
8 ONormal/Square 

9 Oblique/Conitact 

10 Oblique/Weighted 
11 Oblique/Boxed 

12 Oblique/Flattened 
13 Oblique/Rounded 
14 Oblique/Off Center 
15 Oblique/Square 


bMidline (BYTE) 
Midline. 


0 Any 

1 No Fit 

2 Standard/Trimmed 
3 Standard/Pointed 
4 Standard/Serifed 
5 High/Trimmed 

6 High/Pointed 

7 High/Serifed 

8 Constant/Trimmed 
9 Constant/Pointed 
10 Constant/Serifed 
11 Low/Trimmed 

12 Low/Pointed | 
13 Low/Serifed 
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bXHeight (BYTE) 
X-Height. 


0 Any 

1 No Fit 

2 Constant/Smail 

3 Constant/Standard 
4 Constant/Large 

5 Ducking/Small 

6 Ducking/Standard 
7 Ducking/Large 


fbPassed!SO (BYTE) 
Font passed ISO test. 


The following flags indicate those displays and resolutions at which the font complied 
with ISO 9241. 


FM_ISO_9518 640 
FM_ISO_9515 640 
FM_ISO_9515 1024 
FM_ISO_9517_640 
FM_ISO_9517_1024 


fbFailedISO (BYTE) 
Font failed ISO test. 


The following flags indicate those displays and resolutions at which the font did not 
comply with !SO 9241. 


FM_ISO_9518 640 
FM_ISO_9515 640 
FM_ISO_9515_1024 
FM_ISO_9517_640 
FM_ISO_9517_1024 


PARAM 


Presentation parameter attribute definition. 


Syntax 
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Fields 
id (ULONG) 


Attribute type identity. 


These identities are in the range of OxO0000000 to OxFFFFFFFF. The window manager 
uses values of this parameter in the range 0x00000000 to PP_USER; therefore, an 
application cannot define private presentation parameter attribute identities in this range. 
An application should use WinAddAtom to guarantee obtaining a unique identity. 


PP_FOREGROUNDCOLOR 
PP_BACKGROUNDCOLOR 
PP_FOREGROUNDCOLORINDEX 
PP_BACKGROUNDCOLORINDEX 
PP_HILITEFOREGROUNDCOLOR 
PP_HILITEBACKGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLORINDEX 
PP_HILITEBACKGROUNDCOLORINDEX 
PP_DISABLEDFOREGROUNDCOLOR 
PP_DISABLEDBACKGROUNDCOLOR 
PP_DISABLEDFOREGROUNDCOLORINDEX 
PP_DISABLEDBACKGROUNDCOLORINDEX 
PP_BORDERCOLOR 
PP_BORDERCOLORINDEX 
PP_FONTNAMESIZE 

PP_ACTIVECOLOR 
PP_ACTIVECOLORINDEX 


PP_INACTIVECOLOR 
PP_INACTIVECOLORINDEX 


PP_ACTIVETEXTFGN DCOLOR 
PP_ACTIVETEXTFGNDCOLORINDEX 
PP_ACTIVETEXTBGNDCOLOR 
PP_ACTIVETEXTBGNDCOLORINDEX 


PP_INACTIVETEXTFGNDCOLOR 


Foreground color (in RGB) attribute. 
Background color (in RGB) attribute. 
Foreground color index attribute. 
Background color index attribute. 
Highlighted foreground color (in RGB) 
attribute, for example for selected 
menu items. 

Highlighted background color (in RGB) 
attribute. 

Highlighted foreground color index 
attribute. 

Highlighted background color index 
attribute. 

Disabled foreground color (in RGB) 
attribute. 

Disabled background color (in RGB) 
attribute. 

Disabled foreground color index | 
attribute. . 

Disabled background color index 
attribute. 

Border color (in RGB) attribute. 
Border color index attribute. 

Font name and size attribute. 

Active color value of data type RGB. 
Active color index value of data type 
LONG. 

Inactive color value of data type RGB. 
Inactive color index value of data type 
LONG. 

Active text foreground color value of 
data type RGB. 

Active text foreground color index value 
of data type LONG. 

Active text background color value of 
data type RGB. 

Active text background color index 
value of data type LONG. 

Inactive text foreground color value of 
data type RGB. 
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PP_INACTIVETEXTFGNDCOLORINDEX _ 


PP_INACTIVETEXTBGNDCOLOR 
PP_INACTIVETEXTBGNDCOLORINDEX 
PP_SHADOW 


PP_USER 


cb (ULONG) 
Byte count of the ab parameter. 


ab[1] (BYTE) 
Attribute value. 


inactive text foreground color index 
value of data type LONG. 

Inactive text background color value of 
data type RGB. 

Inactive text background color index 
value of data type LONG. 

Changes the color used for drop 
shadows on certain controls. 

This is a user-defined presentation 
parameter. 


The format of a value depends on the attribute type identity as follows: 


PP_FOREGROUNDCOLOR 
PP_BACKGROUNDCOLOR 
PP_FOREGROUNDCOLORINDEX 
PP_BACKGROUNDCOLORINDEX 
PP_HILITEFOREGROUNDCOLOR 
PP_HILITEBACKGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLORINDEX 
PP_HILITEBACKGROUNDCOLORINDEX 
PP_DISABLEDFOREGROUNDCOLOR 


PP_DISABLEDBACKGROUNDCOLOR 


PP_DISABLEDFOREGROUNDCOLORINDEX 


PP_DISABLEDBACKGROUNDCOLORINDEX 


PP_BORDERCOLOR 
PP_BORDERCOLORINDEX 


PP_FONTNAMESIZE 
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Foreground color value of data type 
RGB. 

Background color value of data type 
RGB. 

Foreground color index value of data 
type LONG. 

Background color index value of data 
type LONG. 

Highlighted foreground color value of 
data type RGB. 

Highlighted background color value of 
data type RGB. 

Highlighted foreground color index 
value of data type LONG. 

Highlighted background color index 
value of data type LONG. 

Disabled foreground color value of data 
type RGB. 

Disabled background color value of 
data type RGB. 

Disabled foreground color index value 
of data type LONG. 

Disabled background color index value 
of data type LONG. 

Border color value of data type RGB. 
Border color index value of data type 
LONG. 

Font name and size values, of data 
type PSZ. The string is in two parts, 
separated by a period. The first part is 
the font point size and the second part 


is the font facename, for example, 
“12.Helv.” 


PCH 


Pointer to a character string. 


Syntax 


typedef unsigned char * PCH; = a 


PCSZ 


Pointer to a constant null-terminated string. 


Syntax 


; ypedef const char : PCSZ; a 


PDEVOPENDATA 


Open device-data array. 


This data type points to data whose format is described by the DEVOPENSTRUC data type. 


Syntax 
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PFN 


Pointer to a procedure. 


Syntax 


In the header file, this is a two-part definition as shown below: 


typedef int (APIENTRY PFN) (); 
typedef PFN *PFN; 


PFNWP 


Pointer to a window procedure. 


This is the standard function definition for window procedures. 


Syntax 


The first argument (HWND) is the handle of the window receiving the message. The second 
argument (ULONG) is a message identifier. The third argument (MPARAM) is the first 
message paramenier (mp1). The fourth argument (MPARAM) is the second message 
paramenter (mp2). The function returns an MRESULT. Each message has a specific set of 
possible return codes. The window procedure must return a value that is appropriate for the 
message being processed. 


In the header file, this is a two-part definition as shown below: 

typedef MRESULT (EXPENTRY FNWP) (HWND, ULONG, MPARAM, MPARAM) ; 

typedef FNWP *PFNWP; 

Window procedures must be EXPORTED in the definitions file used by the linker. 
PID 


Process identity. 


Syntax 
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PIX 


Pel count for multi-line entry field. 


Syntax 


PRDINFOS 


Print device information structure (level 3). 


Syntax 


tweeter struct. _PRDINFO3 G 
_. pszPrinterName; 
Se i 

“RSS tAHIS: oe 

 pszStatus; 
pszComment; 
pszDrivers; 

1. time: oe 


NFO3 *PPROINFOS; 


Fields 
pszPrinterName (PSZ) 
Print device name. 


' pszUserName (PSZ) 
_ User who submitted job. 


This parameter is valid only while the job is printing. It is NULL for a job submitted 
locally. 


pszLogAddr (PSZ) 
Logical address (for example LPT1). 


if NULL or an empty string, the printer is not connected to a logical address. 


uJobld (USHORT) 
Identity of current job. 


If 0, no job is printing. 
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fsStatus (USHORT) 
Print destination status. 


Use the mask PRD_STATUS_MASK to determine the print job status: 


PRD_ACTIVE Processing 

PRD_PAUSED Not processing, or paused. 

Use the mask PRJ_DEVSTATUS for further information about print job status: 
PRJ_COMPLETE Job complete 

PRJ_INTERV Intervention required 

PRJ_ERROR Error occurred (in this case, pszStatus may contain a comment 


. about the error) 
PRJ_DESTOFFLINE Print device offline 
PRJ_DESTPAUSED _ Print device paused 
PRJ_NOTIFY Raise alert 
PRJ_DESTNOPAPER Print device out of paper. 


pszStatus (PSZ) 
Print device comment while printing. 


A comment posted by the print processor of the print device. This parameter is valid 
only during printing. 


pszComment (PSZ) 
Print device description. 


pszDrivers (PSZ) 
Drivers supported by print device. 


List items are separated by commas. Each printer driver name may have a device 
name separated by a dot (for example, PLOTTER.HP7475A). The default printer is 
listed first. 


time (USHORT) 
Time job has been printing (minutes) 


This parameter applies only during printing. 


usTimeOut (USHORT) 
Device timeout (seconds) 


The time that elapses before the device driver notifies the spooler that the print device 
has not responded. 
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PRDRIVINFO 


Printer driver information structure (level 0). 


Syntax 


typedef struct PRORIVINFO { _ - ee ee Aiea gaan 
CHAR —_—sszDrivName[DRIV_NAME_SIZE+1+DRIV_DEVICENAME_ SIZE+1]; 
A PRORIVINGO Soe aE ae oe 


“typedef PRORIVINFO *PPRORIVINFO; 


Fields 
szDrivName[DRIV_NAME_SIZE+1+DRIV_DEVICENAME_SIZE+1] (CHAR) 
Name of printer driver. 


This is the name of the printer driver and device is the format of DRIVER.DEVICE. For 
example “IBM4019.IBM Laserprinter E.” 


PRESPARAMS 


Presentation parameter data. 


Syntax 


- typedet PRESPARAMS. *PPRESPARAMS; o 2 eo 


Fields 
cb (ULONG) 
Length of the aparam parameter, in bytes. 


aparam[1] (PARAM) 
Array of presentation attribute parameters. 
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PRINTDEST 
PRINTDEST data structure. 


Contains all the parameters required to issue a DevPostDeviceModes and DevOpenDC 
function calls. 


Syntax 


Fields 
cb (ULONG) 
Length of data structure, in bytes. 


IType (LONG) 
Type of device context. 


OD_QUEUED The device context is queued. 
OD_DIRECT _ The device context is direct. 


pszToken (PSZ) 
Device-information token. 


This is always “.” 


ICount (LONG) 
Number of items. 


This is the number of items present in the pdopData field. 


pdopData (PDEVOPENDATA) 
Open device context data area. 


See DEVOPENSTRUC for information on the format of pdopData. 


fl (ULONG) 
Flags. 


PD_JOB_PROPERTY This flag indicates that DevPostDeviceModes should be called 
with DPDM_POSTJOBPROP before calling DevOpenDC. 
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pszPrinter (PSZ) 
Name of Printer name. 


A name that specifies the device, for example “PRINTER1.” The name is used for calling 
DevPostDeviceModes. 


The printer device name can be found by calling SplQueryQueue and passing to it the 
information found in the pszLogAddress field of the DEVOPENSTRUC structure pointed 
to by pdopData. SplQueryQueue returns a PRQINFOS structure. The pszPrinters field 
in PRQINFOS3 contains the printer device name to be used. 


PRINTERINFO 


Print destination information structure. 


This structure is used at information level 0. 


Syntax 


sdef struct _ _PRINTERINFO c oe 
_ filtype; a ee 
7 - pszComputerName; ee 
_pszPrintDest inat ionName; 
 pszDescription; Le 
le  pszLocalName; 
- \ PRINTERINFO3, 


_typeder pRINTERINFO »PPRINTERINFOs 


Fields 
flType (ULONG) 
Type of printer. 


This is a flag used to describe the type of print destination: 


SPL_PR_QUEUE Print destination is a queue 
SPL_PR_DIRECT_DEVICE Print destination is a direct print device 
SPL_PR_QUEUED_DEVICE Print destination is a queued print device 


pszComputerName (PSZ) 
Computer name. 


A NULL string specifies the local workstation. 


pszPrintDestinationName (PSZ) 
Name of Print Destination. 


This is either a queue name or a print device name depending upon the value of fiType. 
The maximum length of the name in the network case is 256 (including one byte for the 
null terminator). 
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pszDescription (PSZ) 
Description of print destination. 


The maximum length is 48 characters (including one byte for the null terminator). 


pszLocalName (PSZ) 
Local name of remote print destination. 


This is a local port name (for instance “LPT4”) that is connected to the remote print 
destination. A NULL string specifies that no connection exists. 


PRFPROFILE 


Profile structure. 


Syntax 


LE *PPRFPROFI 


Fields 
cchUserName (ULONG) 
Length of user profile name. 


pszUserName (PSZ) 
User profile name. 


echSysLen (ULONG) 
Length of system profile name. 


_pszSysName (PSZ) 
System profile name. 
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PRJINFO2 


Print-job information structure. 


This structure provides a subset of the information supplied by PRJINFO3. It minimizes the 
storage required for job-information retrieval, and is sufficient for most uses. 


Syntax 


typedef struct _PRJINFO2 { 
USHORT uJobId; 
USHORT: -uPriority; 
PSZ __ pszUserName; 
USHORT. uPosition; 
USHORT fsStatus: 
ULONG ulSubmitted; 
ULONG ulSize; | 

PSZ. =-—=—itsSsSép ss zCcommeentt ; 
PSZ pszDocument; 
- } PRJINFO2; 


“typedef PRJINFO2 *PPRJINFO2; 


Fields 
uJobld (USHORT) 
Job identification number. 


uPriority (USHORT) 
Job priority. 
The job-priority range is 1 through 99, with 99 the highest job priority. (For queue 
priorities, 1 is the highest priority.) 


The job priority determines the order of jobs in the queue. If multiple queues print to the 
same printer, the job at the front of each queue is examined. The job with the highest 
priority is printed first; if there is more than one job with the highest priority, the oldest 
job with this priority is printed first. 


PRJ_MAX_PRIORITY — Highest priority 
PRJ_MIN_PRIORITY — Lowest priority 
PRJ_NO_PRIORITY No priority. 


pszUserName (PSZ) 
User who submitted the job. 


This parameter applies only to jobs created by a user and enqueued on a remote server. 
A NULL string signifies a local job. 


uPosition (USHORT) 
Job position in queue. 


If 1, the job is scheduled to be the next job printed from this queue. 
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fsStatus (USHORT) 
Job status. 


To find the job status, use the PRJ_QSTATUS mask: 


PRJ_QS QUEUED Queued 

PRJ_QS_ PAUSED Paused by a SplHoldJob function 
PRJ_QS_SPOOLING Job being created 

PRJ_QS_ PRINTING Printing (bits 2 through 11 are valid). 


For further information, use the PRJ_DEVSTATUS mask: 


PRJ_ COMPLETE Job complete 
PRJ_INTERV Intervention required 
PRJ_ERROR Error occurred. 


PRJ_DESTOFFLINE Print destination offline 
PRJ_DESTPAUSED Print destination paused 
PRJ_NOTIFY Alert should be raised 
PRJ_DESTNOPAPER _ Print destination out of paper 
PRJ_DESTFORMCHG Printer waiting for form change 
PRJ_DESTCRTCHG Printer waiting for cartridge change 
PRJ_DESTPENCHG Printer waiting for pen change. 


This bit indicates that the job is deleted: 
PRJ DELETED Job deleted. 


ulSubmitted (ULONG) 
Time job submitted. 


Time format is the same as that stored in the global information segment. 


ulSize (ULONG) 
Print-job size (bytes). 


pszComment (PSZ) 
Comment string. 


information about the print job. The maximum length of the string is 48 characters 
(including one byte for the null terminator). 


pszDocument (PSZ) 
Document name. 


The document name of the print job (set by the application that submitted the print job). 
~ The maximum length of the string is 260 characters. 
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PRJINFO3 


Print-job information structure. 


This structure is used when complete job details are required. A subset of this information is 
supplied by PRJINFO2. 


Syntax | j 


typedef struct. PRJINFO3 {  . 


‘USHORT udoblds o6528 
~ USHORT : uPriority;. = 9 
PSZ° > pszUserName; 
USHORT — uPosition; 
‘USHORT) fsStatus; 
~ULONG ulSubmitted; 
ULONG > ulSize; 
PSL  pszComment; — 
/PSZ pszDocument; 
PSZ  ==—i‘(‘i‘éié pszNotifyNames 
“57 pszbatatype: 
:  pszParms; 
- PSZ . pszStatus; 
PSZ  pszQueue; 
—PSZ————soepszQProcName; 
| PSZ a pszQProcParms ; 
P PSL cae -pszDriverName; 
- PDRIVDATA pDriverData; 
—PSZ  =—ssi“‘(tssCsCpszPrinterName; 


Fields 
uJobid (USHORT) 
Job identification number. 


uPriority (USHORT) 
Job priority. 


The job-priority range is 1 through 99, with 99 the highest job priority. (For queue 
priorities, 1 is the highest priority.) 


The job priority determines the order of jobs in the queue. If multiple queues print to the 
same printer, the job on the front of each queue is examined. The job with the highest 
priority is printed first; if there is more than one job with the highest priority, the oldest 
job with this priority is printed first. , 


PRJ_MAX_PRIORITY _ Highest priority 
PRJ_MIN_PRIORITY Lowest priority 
PRJ_NO_PRIORITY No priority. 
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pszUserName (PSZ) 
User who submitted the job. 


This parameter applies only to jobs created by a user on a remote workstation and 
queued on a server. A NULL string signifies a local job. 


uPosition (USHORT) 
Job position in queue. 


If 1, the job is scheduled to be the next job printed from this queue. 


fsStatus (USHORT) 
Job status. 


To find the job status, use the PRJU_QSTATUS mask: 


ulSubmitted (ULONG) 
Time job submitted. 


Time format is the same as that stored in the global information segment. 


ulSize (ULONG) 
Print-job size (bytes). 


pszComment (PSZ) 
Comment string. 
Information about the print job. 


The maximum length of the string is 48 characters (including one byte for the null 
terminator). 


pszDocument (PSZ) 
Document name. 


The document name of the print job (set by the application that submitted the print job). 
The maximum length of the string is 260 characters. 


pszNotifyName (PSZ) 
Messaging alias for print alert. 


This parameter is a computer name and applies only to jobs on a remote server queue. 
A NULL string is returned for jobs on a local queue. 


pszDataType (PSZ) 
Data type of submitted file. 


This is specified by the pszDataType parameter in the DEVOPENSTRUC structure 
passed to the DevOpenDC call when the job is created. The name is truncated to fit the 
field if necessary, and contains a trailing NULL. 


pszParms (PSZ) 
Parameters. 


The form of this string is: 


parml=vall parm2=val2 ... 
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pszStatus (PSZ) 
Status comment. 


A text string, posted by the queue processor, that provides additional job-status 
information. The default string type is NULL. 


pszQueue (PSZ) 
Queue name. 


The name of the queue the job is on. 


pszQProcName (PSZ) 
Queue processor. 


The name of the queue processor. 


pszQProcParms (PSZ) 
Queue processor parameters. 


Spaces are used to separate parameters. 


pszDriverName (PSZ) 
Driver name. 


The name of the device driver (for example, “LASERJET”). The device name is part of 
pDriverData. 


pDriverData (PDRIVDATA) 
Job Properties (driver data). 


The contents are specific to the device driver. 


pszPrinterName (PSZ) 
Printer name. 


If the job is printing, the printer name, otherwise NULL. 


PROGRAMENTRY 


Program-entry structure. 


Syntax 
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Fields 
hprog (HPROGRAM) 
Program handle. 


progt (PROGTYPE) 
Program type. 


szTitle[ MAXNAMEL+1] (CHAR) 
Program title (null-terminated). 


PROGCATEGORY 


Program category. 


Syntax 


PROGDETAILS 


Program-details structure. 


Syntax 


Fields 
Length (ULONG) 
‘Length of structure. 


progt (PROGTYPE) 
Program type. 
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pszTitle (PSZ) 
Title. 


pszExecutable (PSZ) 
Executable file name. 


pszParameters (PSZ) 
Parameter string. 


pszStartupDir (PSZ) 
Start-up directory. 


pszicon (PSZ) 
Icon-file name. 


pszEnvironment (PSZ) 
Environment string. 


A list of null-terminated strings, ending with an extra NULL character. 


swplnitial (SWP) 
Initial window position and size. 


PROGTYPE 


Program-type structure. 


Syntax 


uct PROGIVPE ( 
proc; — 
/ mVvisile, 


Fields 
proge (PROGCATEGORY) 
Program category: 


PROG_DEFAULT Default application. 

| PROG_PM Presentation Manager application. 
PROG_WINDOWABLEVIO Text-windowed application. 
PROG_FULLSCREEN Full-screen application. 
PROG_WINDOWEDVDM -PC DOS executable process (windowed). 
PROG_VDM PC DOS executable process (full screen). 
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PROG_REAL PC DOS executable process (full screen). 
Same as PROG_VDM. 


PROG_31_STDSEAMLESSVDM Windows 3.1 program that will execute in its 
own windowed WINOS2 session. 


PROG_31_STDSEAMLESSCOMMON _ Windows 3.1 program that will execute in a 
common windowed WINOS2 session. 


PROG_31_ENHSEAMLESSVDM Windows 3.1 program that will execute in 
enhanced compatibility mode in its own 
windowed WINOS2 session. 


PROG_31_ENHSEAMLESSCOMMON _ Windows 3.1 program that will execute in 
enhanced compatibility mode in a common 
windowed WINOS2 session. 


PROG_31_ENH Windows 3.1 program that will execute in 
enhanced compatibility mode in a full screen 
WINOS2 session. 


PROG_31_STD Windows 3.1 program that will execute in a full 
screen WINOS2 session. 


fbVisible (ULONG) 
Visibility attribute. 


When testing this field, allow for the possibility that other bits may be defined in the 
future. SHE_INVISIBLE and SHE_PROTECTED can be used to mask the visibility and 
protected flags, respectively. 


SHE_VISIBLE Visible 
SHE_INVISIBLE Invisible 
SHE_UNPROTECTED — Unprotected 
SHE_PROTECTED Protected. 


PRPORTINFO 


Port information structure (level 0). 


Syntax 


_ typedef struct _PRPORTINEO { 
| CHAR szPortName[PDLEN+1] 
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Fields 
szPortName[PDLEN+1] (CHAR) 
Name of the port. 


This is the name of the port. For example “LPT1.” 


PRPORTINFO1 


Port information structure (level 1). 


Syntax 


typedef struct _PRPORTINFO1 { 
PSZ pszPortName; 

- PSZ pszPortDriverName; 
PSZ: pszPortDriverPathName; 
} PRPORTINFO1; 


typedef PRPORTINFO! *PPRPORTINFO1; 


Fields 
pszPortName (PSZ) 
Name of the port. 


This is the name of the port. For example “LPT1.” 


pszPortDriverName (PSZ) 
Name of the port driver. 


This is the name of the port driver. For example “PARALLEL.” 


pszPortDriverPathName (PSZ) 
Full path name of the port driver. 


This is the full path name of the port driver. For example 
“C:\OS2\DLL\PARALLEL.PDR.” 
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PRQINFO3 


Print-queue information structure. 


This structure is used at information levels 3 and 4. 


Syntax 


Fields 
pszName (PSZ) 
Queue name. 


The maximum length of the name in the network case is 256 (including one byte for zero 
termination). 


uPriority (USHORT) 
Queue priority. 


The range is 1 through 9, with 1 being the highest queue priority. 


The default job priority (DefJobPrio) is determined from: 
DefJobPrio=100-—(10* uPriority). 
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If a job is added with PRJ_NO_PRIORITY specified, DefJobPrio is used. If a default 
priority higher than the default job priority is specified, the default job priority is used. If 
a default priority lower than the default is specified, the specified job priority is used. 


PRQ_DEF_PRIORITY Default priority 
PRQ_MAX_PRIORITY — Highest priority 
PRQ_MIN_PRIORITY Minimum priority 
PRQ_NO PRIORITY _ No priority. 


uStartTime (USHORT) 
Minutes after midnight when queue becomes active. 


For example, the value 75 represents 1:15 a.m. 


lf uStartTime and uUntilTime are both 0, the print queue is always available. 


uUntilTime (USHORT) 
Minutes after midnight. when queue ceases to be active. 


For example, the value 1200 represents 8 p.m. 


If uUUntilTime and uStartTime are both 0, the print queue is always available. 


fsType (USHORT) | 


Queue type. 
PRQ3_TYPE_RAW Data is always enqueued in the device specific format. 
PRQ3_TYPE_BYPASS Allows the spooler to bypass the queue processor and 


send data directly to the Printer Driver. Setting this bit 

allows the spooler to print jobs of type PM_Q_RAW 

while they are still being spooled. 
PRQ3_TYPE_APPDEFAULT This bit is set for the application default queue only. 


pszSepFile (PSZ) 
Separator-page file. 
The path and file name of a separator-page file on the target computer. 


This file contains formatting information for the page or pages to be used between print 
jobs. A relative path name is taken as relative to the current spool directory. A NULL 
string indicates no separator page. 


pszPrProc (PSZ) 
Default queue-processor. 


pszParms (PSZ) 
Queue parameters. 


This can be any text string or a NULL string. 


pszComment (PSZ) 
Queue description. 


A NULL string results in no comment. The maximum length is 48 characters (including 
one byte for the null terminator). 
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fsStatus (USHORT) 
Queue status. 


PRQ3_PAUSED Queue is paused (held). 
PRQ3_PENDING Queue is pending deletion. 


cJobs (USHORT) 
Number of jobs in queue. 


pszPrinters (PSZ) 
Print devices connected to queue. 


This cannot be NULL. 


pszDriverName (PSZ) 
Default device driver. 


pDriverData (PDRIVDATA) 
Default queue job properties. 


Note: An application can use pszDriverName, pDriverData, pszPrProc, and pszParms 
to construct a valid DevOpenDC call based only on the queue name. 


PRQINFO6 


Print-queue information structure. 


This structure is used at information level 6. 


Syntax 
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Fields 
pszName (PSZ) 
Queue name. 


The maximum length of the name in the network case is 256 (including one byte for zero 
termination). 


uPriority (USHORT) 
Queue priority. 


The range is 1 through 9, with 1 being the highest queue priority. 


The default job priority (DefJobPrio) is determined from: 
DefJobPrio=100-(10* uPriority). 


lf a job is added with PRJ_NO_PRIORITY specified, DefJobPrio is used. If a default 
priority higher than the default job priority is specified, the default job priority is used. If 
a default priority lower than the default is specified, the specified job priority is used. 


PRQ_DEF_PRIORITY Default priority 
PRQ_MAX_PRIORITY _ Highest priority 
PRQ_MIN_PRIORITY Minimum priority 
PRQ_NO_ PRIORITY _ No priority. 


uStartTime (USHORT) 
Minutes after midnight when queue becomes active. 


For example, the value 75 represents 1:15 a.m. 
lf uStartTime and uUntilTime are both 0, the print queue is always available. 


uUntilTime (USHORT) 
Minutes after midnight. when queue ceases to be active. 


For example, the value 1200 represents 8 p.m. 
If uUntilTime and uStartTime are both 0, the print queue is always available. 


‘fsType (USHORT) 


Queue type. 
PRQ3_TYPE_RAW Data is always enqueued in the device specific format. 
PRQ3_TYPE_BYPASS Allows the spooler to bypass the queue processor and 


send data directly to the Printer Driver. Setting this bit 
allows the spooler to print jobs of type PM_Q_RAW 
while they are still being spooled. 


PRQ3_TYPE_APPDEFAULT This bit is set for the application default queue only. 
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pszSepFile (PSZ) 
Separator-page file. 


The path and file name of a separator-page file on the target computer. 


This file contains formatting information for the page or pages to be used between print 
jobs. A relative path name is taken as relative to the current spool directory. A NULL 
string indicates no separator page. 


pszPrProc (PSZ) 
Default queue-processor. 


pszParms (PSZ) 
Queue parameters. 


This can be any text string or a NULL string. 


pszComment (PSZ) 
Queue description. 


A NULL string results in no comment. The maximum length is 48 characters (including 
one byte for the null terminator). 


fsStatus (USHORT) 
Queue status. 


PRQ3_PAUSED Queue is paused (held). 
~ PRQ3_PENDING Queue is pending deletion. 


cJobs (USHORT) 
Number of jobs in queue. 


pszPrinters (PSZ) 
Print devices connected to queue. 


This cannot be NULL. 


pszDriverName (PSZ) 
Default device driver. 


pDriverData (PDRIVDATA) 
Default queue job properties. 


Note: An application can use pszDriverName, pDriverData, pszPrProc, and pszParms 
to construct a valid DevOpenDC call based only on the queue name. 


pszRemoteComputerName (PSZ) 
Remote computer name. 


The computer name part of a remote queue for which this queue is a local alias. 


pszRemoteQueueName (PSZ) 
Remote queue name. 


The queue name part of a remote queue for which this queue is a local alias. 
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PRQPROCINFO 


Queue processor information structure (level 0). 


Syntax 


typedef struct _PROPROCINFO { 
CHAR _szQProcName[QNLE 


~} PROPROCINFO; ~ - 
typedef PROPROCINFO *PPRQPROC 


Fields 
szQProcName[QNLEN+1] (CHAR) 
Name of queue processor. 


This is the name of the queue processor (driver). For example “PMPRINT.” 


POINTERINFO 


Pointer-information structure. 


Syntax 


truct _POINTERINED { 


Fields 
fPointer (ULONG) 
Bit-map size indicator. 


TRUE Pointer-sized bit map 
FALSE _ Icon-sized bit map. 


xHotSpot (LONG) 
X-coordinate of action point. 
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yHotSpot (LONG) 
Y-coordinate of action point. 


hbmPointer (HBITMAP) 
Bit-map handle. of pointer. 


hbmColor (HBITMAP) 
Bit-map handle of color bit map. 


hbmMiniPointer (HBITMAP) 
Bit-map handle of a pointer to a mini bit map. 


hbmMiniColor (HBITMAP) 
Bit-map handle of mini color bit map. 


POINTL 


Point structure (long integers). 


Syntax 


“POINTL *PPOINTL; 


Fields 
x (LONG) 
X-coordinate. 


y (LONG) 
Y-coordinate. 
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POINTS 


Point structure (short integers). 


Syntax 


typedef struct POINTS { 
SHORT X3 She 
SHORT y:; 

} POINTS; 


typedef POINTS *PPOINTS; 


Fields 
x (SHORT) 
X-coordinate. 


-y (SHORT) 
Y-coordinate. 


PQMOPENDATA 


Open queue-manager data array. 


This data type points to data whose format is described by the DEVOPENSTRUC data type. 


Syntax 


“typedef PSZ * POMOPENDATA; = 


PSZ 


Pointer to a null-terminated string. 


If you are using C++ **, you may need to use PCSZ. 


Syntax 
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PWPOINT 
Pointer to a WPOINT data structure. 


ee 


ee 
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Fields 
hwnd (HWND) 
Window handle. 


msg (ULONG) 
Message identity. . 


mp1 (MPARAM) 
Parameter 1. 
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mp2 (MPARAM) 
Parameter 2. 


time (ULONG) 
Message time. 


pti (POINTL) 
Pointer position when message was peneried 


reserved (ULONG) 
Reserved. 


QUERYRECFROMRECT 
Structure that contains information about a container record that is bounded by a specified 
rectangle. This structure is used in the CM_QUERYRECORDFROMRECT container 
message only. See “CM_QUERYRECORDFROMRECT” on page 22-62 for information 
about that message. 


Syntax 


: typede? Strict _QueRrRecrnonme 
ULONG cb: aa 
RECTL © o srects: 
ULONG fsSearch; 
S ua QUERYRECFROMRECT 


“typedef QUERYRECFROMRECT *PQUE 


Fields 
cb (ULONG) 
Structure size. 


The size (in bytes) of the QUERYRECFROMRECT data structure. 


rect (RECTL) 
Rectangle. 


The rectangle to query, in virtual coordinates relative to the container window origin. If 
the details view (CV_DETAIL) is displayed, the x-coordinates of the rectangle are 
ignored. 


fsSearch (ULONG) 
Search control flags. 


One flag from each of the following groups can be specified: 


e Search sensitivity: 
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CMA_COMPLETE 
Returns the container records that are completely within the bounding rectangle. 


CMA_PARTIAL 
Returns the container records that are completely or partially within the bounding 
rectangle. 
¢ Enumeration order: 


CMA_ITEMORDER 
Container records are enumerated in item order, lowest to highest. 


CMA_ZORDER 
Container records are enumerated by z-order, from top to bottom. This flag is 
valid for the icon view only. 


QUERYRECORDRECT 
Structure that contains information about the rectangle of the specified container record, 
relative to the container window origin. This structure is used in the 
CM_QUERYRECORDRECT container message only. See “CM_QUERYRECORDRECT” on 
page 22-64 for information about that message. 


Syntax 


tract _nuenveeconorect ce 
oe cbs 

- pRecord; oe 
_ FRhESpTEWindon | 


_fsExtent; 
YRECORORECTS ae 


peal UERYRECORDRECT 5 sPquenvsecononccr, oo 


Fields 
cb (ULONG) 
Structure size. 


The size (in bytes) of the QUERYRECORDRECT structure. 


pRecord (PRECORDCORE) 
Pointer. 


Pointer to the specified RECORDCORE data structure. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is 
created, then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data 
structures and messages. 
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fRightSplitWindow (ULONG) 
Window flag. 


Flag that specifies the right or left window in the split details view. 


This flag is ignored if the view is not the split details view. 


TRUE Right split window is returned. 
FALSE Left split window is returned. 


fsExtent (ULONG) 
Rectangle flags. 


Flags that specify the extent of the desired rectangle. 


These flags can be combined by using a logical OR operator (|) to return the rectangle 
that bounds the icon, the expanded and collapsed icon or bit map, and the text. 


CMA_ICON Returns the icon rectangle. 

CMA_TEXT Returns the text rectangle. 

CMA_TREEICON _ Returns the rectangle of the expanded and collapsed icons or bit 
maps. This flag is valid for the tree icon and tree text views only. 


RECORDCORE 


Structure that contains information for records in a container control. This data structure is 
used if the CCS_MINIRECORDCORE style bit is not specified when a container is created. 


Syntax 


tyoedet’ struct _REconoCoRE 

ULONG — ee 
~ ULONG 
| POINTL ee 
| struct _RECOROCORE 

PSZ 

“HPOINTER 
HBITMAP — oe Rimini ans Se 

- pote. 
-pszName; ee 
ee 


Fields 
cb (ULONG) 
The size, in bytes, of the RECORDCORE structure. 
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flRecordAttr (ULONG) 
Container record attributes. 


This parameter can contain any or all of the following: 
CRA_COLLAPSED Specifies that a record is collapsed. 
CRA_CURSORED Specifies that a record will be drawn with a selection cursor. 


CRA_DISABLED _ Specifies that a record will be drawn with unavailable-state 
emphasis. 


CRA_DROPONABLE _ Specifies that a record can be a target for direct manipulation. 
CRA_EXPANDED Specifies that a record is expanded. 


CRA_FILTERED Specifies that a record is filtered and, therefore, hidden from 
view. 

CRA_INUSE Specifies that a record will be drawn with in-use emphasis. 

CRA_PICKED Specifies that the container record willl be picked up as part of 
the drag set. 

CRA_SELECTED Specifies that a record will be drawn with selected-state 
emphasis. 

CRA_SOURCE Specifies that a record will be drawn with source-menu 
emphasis. 


- ptllcon (POINTL) 
Position of a container record in the icon view. 


preccNextRecord (struct RRECORDCORE *) 
Pointer to the next linked record. 


pszicon (PSZ) 
Text for the icon view (CV_ICON). 


hptricon (HPOINTER) 
Icon that is displayed when the CV_MINI style bit is not specified. 


This field is used when the CA_DRAWICON container attribute of the CNRINFO data 
structure is set. 


hptrMinilcon (HPOINTER) 
Icon that is displayed when the CV_MINI style bit is specified. 


This field is used when the CA_DRAWICON container attribute of the CNRINFO data 
structure is set. 


hbmBitmap (HBITMAP) 
Bit map displayed when the CV_MINI style bit is not specified. 


This field is used when the CA_DRAWBITMAP container attribute of the CNRINFO data 
structure is set. 
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hbmMiniBitmap (HBITMAP) 
Bit map displayed when the CV_MINI style bit is specified. 


This field is used when the CA_DRAWBITMAP container attribute of the CNRINFO data 
structure is set. 


pTreeltemDesc (PTREEITEMDESC) 
Pointer to a TREEITEMDESC structure. 


The TREEITEMDESC structure contains the icons and bit maps used to represent the 
state of an expanded or collapsed parent item in the tree name view. 


pszText (PSZ) 
Text for the text view (CV_TEXT). 


pszName (PSZ) 
Text for the name view (CV_NAME). 


pszTree (PSZ) 
Text for the tree view (CV_TREE). 


RECORDINSERT 
Structure that contains information about the RECORDCORE structure or structures that are 
being inserted into a container. The RECORDINSERT structure is used in the 
CM_INSERTRECORD container message only. See “CM_INSERTRECORD?” on 
page 22-45 for information about that message. 


Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, 
then MINIRECORDCORE should be used instead of RECORDCORE and 
PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable 
data structures and messages. 


Syntax 


rdOrders 
RecordParent: 


Fields 
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cb (ULONG) 
Structure size. 


The size (in bytes) of the RECORDINSERT structure. 
pRecordOrder (PRECORDCORE) 
Record order. 
Orders the RECORDCORE structure or structures relative to other RECORDCORE 
structures in the container. The values can be: 
CMA_FIRST Places a RECORDCORE structure, or list of RECORDCORE structures, 
at the beginning of the list of structures. 


CMA_END Places a RECORDCORE structure, or list of RECORDCORE structures, 
at the end of the list of structures. 


Other Pointer to a RECORDCORE structure that this structure, or list of 
structures, is to be inserted after. 
pRecordParent (PRECORDCORE) 
Pointer to record parent. 


Pointer to a RECORDCORE structure that is the parent of the record or records to be 
inserted. This field is used only with the CMA_FIRST or CMA_END attributes of the 
pRecordOrder field. 


finvalidateRecord (ULONG) 
Update flag. 
Flag that indicates an automatic display update after RECORDCORE structures are 
inserted. . 
TRUE _ The display is automatically updated after a RECORDCORE structure is 
inserted. 
FALSE The application must send the CM_INVALIDATERECORD message after a 
RECORDCORE structure is inserted. 
zOrder (ULONG) 
Record z-order. 
Positions the RECORDCORE structure in z-order, relative to other records in the 
container. The values can be: 
CMA_TOP _ Places a RECORDCORE structure at the top of the z-order. This is 
the default value. 
CMA_BOTTOM Places a RECORDCORE structure at the bottom of the z-order. 
cRecordsinsert (ULONG) | 
Number of root level structures. 


The number of root level RECORDCORE structures to be inserted. The cRecordsinsert 
field value must be greater than 0. 
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RECTL 


Rectangle structure. 


Syntax 


_ typedef struct RECTL { 
LONG = xxLeft; 
LONG = -yBottom;) 
LONG =” xRight; 
LONG ———s-yTop;- 
‘} RECTL; 


“typedef RECTL *PRECTL; 


Fields 
xLeft (LONG) 
X-coordinate of left-hand edge of rectangle. 


yBottom (LONG) 
Y-coordinate of bottom edge of rectangle. 


_xRight (LONG) 
X-coordinate of right-hand edge of rectangle. 


yTop (LONG) 
Y-coordinate of top edge of rectangle. 


RENDERFILE 


File-rendering structure. 


Syntax 


Appendix A. Data Types A-179 


Fields 
hwndDragFiles (HWND) 
Conversation handle. 


Created by DrgDragFiles. 


hstrSource (HSTR) 
Handle to source file name. 


hstrTarget (HSTR) 
Handle to target file name. 


fMove (USHORT) 
Operation. 


TRUE Move the file. 
FALSE Copy the file. 


usRsvd (USHORT) 
Reserved. 


RGB 


RGB color value. 


Syntax 


Fields 
bBlue (BYTE) 
Blue component of the color definition. 


bGreen (BYTE) 
Green component of the color definition. 


bRed (BYTE) 
Red component of the color definition. 
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RGB2 


RGB color value. 


Syntax 


typedef struct RGB2 { 
bBlue;: 


- BYTE 
BYTE 
BYTE 
BYTE 

} RGB2; 


- bGreen; 
bRed; 


typedef RGB2 *PRGB2; 


Fields 
bBlue (BYTE) 


fcOptions; 


Biue component of the color definition. 


bGreen (BYTE) 


Green component of the color definition. 


bRed (BYTE) 


Red component of the color definition. 


fcOptions (BYTE) 
Entry options. 


These can be ORed together if required: 


PC_RESERVED 


PC_EXPLICIT 


The color entry is reserved for animating color with the palette 
manager. 


The low-order word of the color table entry designates a physical 
palette slot. This allows an application to show the actual contents 
of the device palette as realized for other logical palettes. This does 
not prevent the color in the slot from being changed for any reason. 
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RGNRECT 


Region-rectangle structure. 


Syntax 


"typedef RGNRECT xPRGNRECTS 


Fields 
ircStart (ULONG) 
Rectangle number from which to start enumerating. 


Numbering starts from 1. 


~ ere (ULONG) 
Number of rectangles that can be returned. 


This must be 1 or greater. 


crcReturned (ULONG) 
Number of rectangles returned. 


A value of less than crc indicates that there are no more rectangles to enumerate. 


ulDirection (ULONG) 
Direction in which the returned rectangles are to be ordered. 


This ordering uses the leading edge of a rectangle: 


RECTDIR_LFRT_TOPBOT _Left-to-right, top-to-bottom 
RECTDIR_RTLF_TOPBOT _ Right-to-left, top-to-bottom 
RECTDIR_LFRT_BOTTOP _Left-to-right, bottom-to-top 
RECTDIR_RTLF_BOTTOP _ Right-to-left, bottom-to-top 


SBCDATA | 


Scroll-bar control data structure. 
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Syntax 


typedef struct _SBCDATA { 

USHORT Cbs 

USHORT sHilite; 
SHORT posFirst; 
SHORT posLast; 
SHORT posThumb;. 
SHORT cVisible; 
SHORT clotal; 

}. SBCDATA; 


typedef. SBCDATA *PSBCDATA; 


Fields 
cb (USHORT) 
Length of control data in bytes. 


The length of the control data for a scroll-bar control. 


This indicates which part of the scroll bar is to be highlighted, if any. 


SHilite (USHORT) 
Highlighting code. 


ZERO No highlighting 
SB_LINEUP Line up arrow 
SB_LINELEFT Line left arrow 
SB_LINEDOWN Line down arrow 
SB_LINERIGHT Line right arrow 
SB_PAGEUP Page up arrow 
SB_PAGELEFT Page left arrow 


SB PAGEDOWN _ Page down arrow 
SB_PAGERIGHT Page right arrow 
SB_SLIDERTRACK _ Slider. 


posFirst (SHORT) 
First bound of the scroll-bar range. 


é 
posLast (SHORT) 
Last bound of the scroll-bar range. 


posThumb (SHORT) 
Slider position. 


cVisible (SHORT) 
Number of data items visible. 


cTotal (SHORT) 
Number of data items available. 
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SEARCHSTRING 


Structure that contains information about the container text string that is the object of the 
search. This structure is used in the CM_SEARCHSTRING container message only. See 
“CM_SEARCHSTRING?’ on page 22-71 for information about that message. 


Syntax 


def EARCHSTRING *PSEARCHSTRING; : oe : 


Fields 
cb (ULONG) 
Structure size. 


The size (in bytes) of the SEARCHSTRING structure. 


pszSearch (PSZ) 
Pointer to the search string. 


fsPrefix (ULONG) 
Search flag. 


Search flag that defines the criteria by which the string specified by the pszSearch field 
is to be compared with the text of the container records to determine the pointer to the 
first matching record. 


TRUE Matching occurs if the leading characters of the container record are the 
characters specified by the pszSearch field. 


FALSE Matching occurs if the container record contains a substring of the characters 
specified by the pszSearch field. 


fsCaseSensitive (ULONG) 
Case sensitivity flag. 


.Y 


Determines case sensitivity of the search. 


TRUE __ The search is case sensitive. 
FALSE The search is not case sensitive. 
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usView (ULONG) 
View to search. 


Search one of the container views for the string. Valid values are: 


* CV_ICON 
¢ CV_NAME 
° CV_TEXT 
¢ CV_TREE 
* CV_DETAIL. 


SEGOFF 
_ 2-byte segment offset in bytes. 


Syntax 


SFACTORS 


Scaling factors. See DevEscape. 


Syntax 


Fields 
x (LONG) . . 
X-scaling factor, as an exponent of 2. 


y (LONG) 
Y-scaling factor, as an exponent of 2. 
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SHORT : 
Signed integer in the range -32 768 through 32 767. 


Syntax 


SIZEF 


Size structure (FIXED values). 


Syntax 


Fields 
ex (FIXED) 
Width. 


cy (FIXED) 
Height. 


SIZEL 


Size structure (LONG values). 


Syntax 
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Fields 
cx (LONG) 
Width. 


cy (LONG) 
Height. 


SLDCDATA 


Slider control data structure. 


Syntax 


typedef struct _SLDCDATA { 

- ULONG: — cbSize; 

USHORT usScalelIncrements; 
USHORT - cusScalelSpacing; 
USHORT usScale2Increments; © 
USHORT - usScale2Spacings — 

} SLDCDATA; ~ 


“typedef SLDCDATA *PSLDCDATA; 


Fields 
cbSize (ULONG) 
Data length. 


Length of the control data in bytes. 


usScale1Increments (USHORT) 
Scale increments. 


The number of increments to set for the slider control. This number represents the 
range of values that can be selected within the slider when the SLS- PRIMARYSCALE1 
style bit is specified. 


usScale1Spacing (USHORT) 
Scale spacing. 


The spacing between increments, expressed in pixels. It represents the unit that is the 
smallest division of the scale when the SLS_PRIMARYSCALE1 style bit is specified. If 
0 is specified, the slider automatically calculates the spacing based on the window size 
and the number of increments specified. 


usScale2Increments (USHORT) 
Alternate scale increments. 


An alternate number of increments to set for the slider control. This number represents 
the range of values that can be selected within the slider when the 
SLS_PRIMARYSCALE2 style bit is specified. 
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usScale2Spacing (USHORT) 
Alternate scale spacing. 


An alternate spacing between increments, expressed in pixels. It represents the unit 
that is the smallest division of the scale when the SLS_PRIMARYSCALE2 style bit is 
specified. If 0 is specified, the slider automatically calculates the spacing based on the 
window size and the number of increments specified. 


SMHSTRUCT 


Send-message-hook structure. 


Syntax 


struct _SMHSTRUCT { 


Fields 
mp2 (MPARAM) 
Parameter 2. 


mp1 (MPARAM) 
Parameter 1. 


msg (ULONG) 
Message identity. 


hwnd (HWND) 
Window handle. 


model (ULONG) 
Message identity. 
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SPBCDATA 


Spin Button control data structure. 


Syntax 


typedef struct SPBCDATA{ = = 
ULONG ulTextLimit; 
LONG ‘lLowerLimit; — 
LONG 1UpperLimit; 
ULONG = —sidMasterSpb; 


PVOID. ~—spHWXCtIDatas; 
} SPBCDATA; oS 


‘typedef SPBCDATA *PSPBCDATA;, 


The SPBCDATA structure is used in WinCreateWindow’s pCtiData parameter. 


When using this structure the SPBM_SETLIMITS, SPBM_SETTEXTLIMIT, and 
SPBM_SETMASTER messages do not need to be specified. 


e ulTextLimit and ILowerLimit replace SPBM_SETLIMITS. 
e /UpperLimit replaces SPBM_SETTEXTLIMIT. 
e idMasterSpb replaces SPBM_SETMASTER. 


Fields 
cbSize (ULONG) 
Size of control block. 


ulTextLimit (ULONG) 
Entryfield text limit. 


ILowerLimit (LONG) 
Spin lower limit (numeric only). 


IUpperLimit (LONG) 
Spin upper limit (numeric only). 


idMasterSpb (ULONG) 
ID of the servant’s master spinbutton. 


pHWXCtIData (PVOID) 
Reserved for Pen Ct/Data. 
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SPLERR 
Error value in the range 0 to 65 535. 


Syntax 


STR16 


‘String of characters, with an implicit length, in a 16-byte field. 


Syntax 


STR32 


String of characters, with an implicit length, in a 32-byte field. 


Syntax 


STR64 


String of characters, with an implicit length, in a 64-byte field. 


Syntax 
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STR8 


String of 8 characters. 


Syntax 


STYLECHANGE 
Style-change structure. This structure is returned by the FNTM_STYLECHANGED message. 


All “old” fields describe the style attributes before the user made a change. The other, or 
“new”, parameters describe the style that will be in effect after this is passed to 
WinDefFontDigProc. When the “old” and “new” values are the same, the user made no 
change. 


For further details of the parameters, see FONTDLG. 


Syntax 
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Fields 
usWeight (USHORT) 
New weight of font. 


usWeightOld (USHORT) 
Old weight of font. 


usWidth (USHORT) 
New width of font. 


usWidthOld (USHORT) 
Old width of font. 


flType (ULONG) 
New type of font. 


flTypeOld (ULONG) 
Old type of font. 


flTypeMask (ULONG) 
New type mask. 


flTypeMaskOld (ULONG) 
Old type mask. 


flStyle (ULONG) 
New selected style bits. 


fiStyleOld (ULONG) 
Old selected style bits. 


flStyleMask (ULONG) 
New mask of style bits to use. 


flStyleMaskOld (ULONG) 
Old mask of style bits to use. 
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SWBLOCK 


Switch-list block structure. 


Syntax 


typedef struct _ SWB 
 ULONG 
SWENTRY — 


~ ) SWBLOCK; 


typedef SWBLOCK *PSWBLOC 


Fields 
cswentry (ULONG) 
Count of switch list entries. 


aswentry[1] (SWENTRY) | 
Switch list entries. 


SWCNTRL 


Switch-list control block structure. 


Syntax 
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Fields 
hwnd (HWND) 
Window handle. 


hwndicon (HWND) 
Window-handle icon. 


hprog (HPROGRAM) 
Program handle. 


idProcess (PID) 
Process identity. 


idSession (ULONG) 
Session identity. 


uchVisibility (ULONG) 
Visibility: 
SWL_VISIBLE Visible in startup list 
SWL_INVISIBLE _ invisible in startup list 


SWL_GRAYED Item cannot be switched to (note that it is not actually grayed in the 
. list). 


fbJump (ULONG) 
Jump indicator: 


SWL_JUMPABLE Participates in jump sequence 
SWL_NOTJUMPABLE Does not participate in jump sequence. 


szSwtitle[ MAXNAMEL+4] (CHAR) 
Switch-list control block title (null-terminated). 


bProgType (ULONG) 
Program type. 


Possible values are: 


PROG DEFAULT 


0 
PROG_FULLSCREEN 1 
PROG_WINDOWABLEVIO 2 
PROG_PM 3 
PROG_VDM 4 
PROG_WINDOWEDVDM 7 


Although there are several other program types for WIN-OS/2 programs, these do not 
show up in this structure. Instead, the PROG_VDM or PROG_WINDOWEDVDM 
program types are used. For instance, for PROG_31_STDSEAMLESSVDM, 
PROG_WINDOWEDVDM is used. This is because all the WIN-OS/2 programs run in 
DOS sessions. For example, if a program is a windowed WIN-OS/2 program, it runs in 
a PROG_WINDOWEDVDM session. Likewise, if it's a full-screen WIN-OS/2 program, it 
runs in a PROG_VDM session. . 
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SWENTRY 


Switch-list entry structure. 


Syntax 


typedef struct SWENTRY { 
HSWITCH fiswitchy). 8 
SWCNTREL ~-swetl; 


} SWENTRY;. 


typedef SWENTRY *PSWENTRY; 


Fields 
hswitch (HSWITCH) 
Switch-list entry handle. 


swetl (SWCNTRL) 
Switch-list control block structure. 


SWP 


Set-window-position structure. 


Syntax 


 hwndInsertB 
tends 

ONG ——_ulReserved1 
6 ——_ulReserved2 


“typedef SUP »PSWP; 
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Fields 
fl (ULONG) 
Options. 


In alphabetic order: 


SWP_ACTIVATE 
SWP_DEACTIVATE 
SWP_HIDE 
SWP_MAXIMIZE 
SWP_MINIMIZE 
SWP_MOVE 
SWP_NOADJUST 
SWP_NOERASEWINDOW 
SWP_NOREDRAW 
SWP_RESTORE 
SWP_SHOW 
SWP_SIZE 
SWP_ZORDER 


cy (LONG) 
Window height. 


cx (LONG) 
Window width. 


y (LONG) 
Y-coordinate of origin. 


x (LONG) 
X-coordinate of origin. 


hwndinsertBehind (HWND) 
Window behind which this window is placed. 


hwnd (HWND) 
Window handle. 


ulReserved1 (ULONG) 
Reserved value, must be 0. 


ulReserved2 (ULONG) 
Reserved value, must be 0. 
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TID 
Thread identity. 


Syntax 


TRACKINFO 


Tracking-information structure. 


Syntax 


_ eyKeyboard; 
 relTrack; 


 ptiMinTrackSize; 


Fields | 
cxBorder (LONG) 
Border width. 


The width of the left and right tracking sides. 


cyBorder (LONG) 
Border height. 


The height of the top and bottom tracking sides. 


cexGrid (LONG) 
Grid width. 


The horizontal bounds of the tracking movements. 
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cyGrid (LONG) 
Grid height. 


The vertical bounds of the tracking movements. 


cxKeyboard (LONG) 
Character cell width movement for arrow key. 


cyKeyboard (LONG) 
Character cell height movement for arrow key. 


reiTrack (RECTL) 
Starting tracking rectangle. 


This is modified as the rectangle is tracked and holds the new tracking position, when 
tracking is complete. 


rciBoundary (RECTL) 
Boundary rectangle. 


This is an absolute bounding rectangle that the tracking rectangle cannot extend; see 
also TF_ALLINBOUNDARY. 


ptiMinTrackSize (POINTL) 
Minimum tracking size. 


ptIMaxTrackSize (POINTL) 
Maximum tracking size. 


fs (ULONG) 
Tracking options. 


In alphabetic order: 


TF_ALLINBOUNDARY The default tracking is such that some part of the tracking 
rectangle is within the bounding rectangle defined by 
rclBoundary. This minimum size is defined by cxBorder and 
cyBorder. 


If TF_ALLINBOUNDARY is specified, the tracking is 
performed so that no part of the tracking rectangle ever falls 
outside of the bounding rectangle. 


TF_BOTTOM Track the bottom side of the rectangle. 

TF_GRID Tracking is restricted to the grid defined by cxGrid and 
cyGrid. — 

TF_LEFT Track the left side of the rectangle. 

TF_MOVE Track all sides of the rectangle. 

TF_RIGHT Track the right side of the rectangle. 
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TF_SETPOINTERPOS The pointer is repositioned according to other flags as 
follows: 


none Pointer is centered in the tracking rectangle. 
TF_MOVE Pointer is centered in the tracking rectangle. 


TF_LEFT Pointer is vertically centered at the left of the 
tracking rectangle. 


TF_TOP Pointer is horizontally centered at the top of 
the tracking rectangle. 


TF_RIGHT Pointer is vertically centered at the right of 
the tracking rectangle. 


TF_BOTTOM Pointer is horizontally centered at the bottom 
of the tracking rectangle. 


TF_STANDARD cx, cy, cxGrid, and cyGrid are all se of cxBorder and 
cyBorder. 
TF_TOP Track the top side of the rectangle. 
TREEITEMDESC 


Structure that contains icons and bit maps used to represent the state of an expanded or 
collapsed parent item in the tree name view of a container control. 


Syntax 


_ typedef A UHCE VRGEUEGMDESY { 
 HBITMAP - ~ hbmExpanded; 

| HBITMAP hbmCol lapsed; 
HPOINTER —_ hptrrExpanded;, 


-HPOINTER PpEEON anSeas 
4 TREEITEMDESC; 


2 typeder TREEITEWDESC »PTREEITENDESC 


Fields 
hbmExpanded (HBITMAP) 
Expanded bit-map handle. 


The handle of the bit map to be used to represent an expanded parent item in the tree 
name view. 


hbmCollapsed (HBITMAP) 
Collapsed bit-map handle. 


The handle of the bit map to be used to represent a collapsed parent item in the tree 
name view. 
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hptrExpanded (HPOINTER) 
Expanded icon handle. 


The handle of the icon to be used to represent an expanded parent item in the tree 
name view. 


hptrCollapsed (HPOINTER) 
Collapsed icon handle. 


The handle of the icon to be used to represent a collapsed parent item in the tree name 
view. 


TREEMOVE 


Data structure for moving nodes in the tree to a new parent. 


Syntax 


Fields 
preccMove (PRECORDCORE) 
Record to be moved. 


preccNewParent (PRECORDCORE) 
New parent for preccMove. 
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pRecordOrder (PRECORDCORE) 
Record order for siblings. 


Possible values are described in the following list: 


CMA_FIRST  preccMove moves to the FIRST child position of preccNewParent. If 
preccNewParent is NULL, preccMove becomes the first root level record 
of the container. 


CMA_LAST _ preccMove moves to the LAST child position of preccNewParent. If 
preccNewParent is NULL, preccMove becomes the last root level record 
of the container. 


Other preccMove moves after this record in the list of children of 
preccNewParent If preccNewParent is NULL, preccMove moves after the 
record specified by pRecordOrder only if that record is also a root level 
record. 


Note: This record must currently exist in the list of children of 
preccNewParent. 


fiMoveSiblings (BOOL) 
Flag indicating whether to move siblings. 


TRUE All siblings of preccMove. that FOLLOW it (from its original location) move to 
the new parent as well. pRecordOrder applies if this flag is TRUE. 


FALSE Only preccMove itself moves to the new parent; all siblings remain with the old 
parent. : 


UCHAR 


Single-byte unsigned character, or unsigned integer in the range 0 through 255. 


Syntax 


ULONG 
Unsigned integer in the range 0 through 4 294 967 295. 


Syntax 
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USERBUTTON 


User-button data structure. 


Syntax 


“pete struct USERBUTTON 
—HWND - hwnd; oe 
\HPS) hose 
. ULONG aa S Le 
(ULONG = fsStateOld; 

E USERBUTTON; 


: typeder | USERBUTTON *PUSERB 


Fields 
hwnd (HWND) 
Window handle. 


hps (HPS) 
. Presentation-space handle. 


fsState (ULONG) 
New state of user button. 


fsStateOld (ULONG) 
Old state of user button. 


USHORT 
Unsigned integer in the range 0 through 65 535. 


Syntax 
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VIOSIZECOUNT 


Count of VIO cell sizes. See DevEscape. 


Syntax 


typedef struct _VIOSIZECOUNT { 
LONG maxcount; 
LONG count: 

} VIOSIZECOUNT; 


typedef VIOSIZECOUNT *PVIOSIZECOUNT; 


Fields 
maxcount (LONG) 
Maximum number of VIO cell sizes supported. 


count (LONG) 
Number of VIO cell sizes returned. 


VIOFONTCELLSIZE 


VIO cell size. See DevEscape. 


Syntax 


" eypeter struct _VIOFONTCELLSIZE foe, 
LONG cS : 
LONG — ; S 

} VIOFONTCELLSIZE: 


typedef VIOFONTCELLSIZE *PVIOFONTCELLSIZE; 


Fields 
cx (LONG) 
Cell width. 


cy (LONG) 
Cell height. 
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VOID 


A data area of undefined format. 


Syntax 


VSCDATA 


Structure that contains information about the value set control. 


Syntax 


Fields 
cbSize (ULONG) 
Data length. 


Length of the control data in bytes. 


usRowCount (USHORT) 
Number of rows. 


The number of rows in the value set control. The minimum number of rows is 1 and the 
maximum number of rows is 65,535. 


usColumnCount (USHORT) 
Number of columns. 


The number of columns in the value set control. The minimum number of columns is 1 
and the maximum number of columns is 65,535. 


A-204 PM Programming Reference Vol II 


VSDRAGINFO 
Structure that contains information about direct manipulation actions that occur over the 
value set control. 


Syntax 


typedef struct _VSDRAGINFO{ 
PDRAGINFO pDragInfo; on 
USHORT ~ usRow; 
USHORT usColumn; © 

} VSDRAGINFO; 


typedef VSDRAGINFO *PVSDRAGINFO; 


Fields 
pDragInfo (PDRAGINFO) 
Pointer to a DRAGINFO structure. 


usRow (USHORT) 
Row index. 


The index of the row over which the direct manipulation action occurred. 


usColumn (USHORT) 
Column index. 


The index of the column over which the direct manipulation action occurred. 


VSDRAGINIT 
Structure that contains information that is used to initialize a direct manipulation action over 
the value set control. 


Syntax 


-_YSORAGINI 
hwnd; 
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Fields 
hwnd (HWND) 
Value set window handle. 


Window handle of the value set control. 


x (LONG) 
X-coordinate. 


X-coordinate of the pointing device pointer in desktop coordinates. 


y (LONG) 
Y-coordinate. 


Y-coordinate of the pointing device pointer in desktop coordinates. 


cx (LONG) 
X-offset. 


X-offset from the hot spot of the pointing device pointer, in pels, to the item origin. The 
item origin is the lower left corner of the item. 


cy (LONG) 
Y-offset. 


Y-offset from the hot spot of the pointing device pointer, in pels, to the item origin. The 
item origin is the lower left corner of the item. 


usRow (USHORT) 
Row index. 


The index of the row over which the direct manipulation action occurred. 


usColumn (USHORT) 
Column index. 


The index of the column over which the direct manipulation action occurred. 


VSTEXT 


Value set text structure. This structure is used with the VM_QUERYITEM message only. 
See “VM_QUERYITEM’” on page 26-10 for information about that message. 


Syntax 
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Fields 
pszitemText (PSZ) 
Pointer to a buffer to copy the string into. 


ulBufLen (ULONG) 
Buffer size. 


Size of the buffer pointed to by the psz/temText field. 


WNDPARAMS 


Window parameters. 


Syntax 


typedef struct _WNDPARAMS { 

ULONG fsStatus; 

ULONG cchText; 

PSZ psztext; 

ULONG cbPresParams; 

PVOID ._-._ pPresParams; 

ULONG cbCtI Data; 
 PVOID pCtiData; 

} WNDPARAMS ; 


typedef WNDPARAMS *PWNDPARAMS ; 


Fields 
fsStatus (ULONG) 
Window parameter selection. 


Identifies the window parameters that are to be set or queried: 


WPM_CBCTLDATA Window control data length 


WPM_CCHTEXT Window text length 
WPM_CTLDATA Window control data 
WPM_PRESPARAMS _ Presentation parameters 
WPM_TEXT Window text. 


cchText (ULONG) 
Length of window text. 


pszText (PSZ) 
Window text. 


cbPresParams (ULONG) 
Length of presentation parameters. 


pPresParams (PVOID) 
Presentation parameters. 
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cbCtiData (ULONG) 
Length of window class specific data. 


pCtiData (PVOID) 
Window class specific data. 


WPOINT 


Window-point data structure (long integers). See POINTL for the form of the structure. 


Syntax 


‘#define WPOINT POINTL = 


~WRECT 


Window-rectangle data structure. See RECTL for the form of the structure. 


Syntax 


XYWINSIZE 


_ Window position and size structure. 


Syntax 
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Fields 
x (SHORT) 
X-coordinate of window origin. 


y (SHORT) 
Y-coordinate of window origin. 


cx (SHORT) 
Window width. 


cy (SHORT) 
Window height. 


fsWindow (USHORT) 
Window options. 


The values may be ORed together. For example, an invisible iconic window can be 
created. Note that if both XYF_MINIMIZED and XYF_MAXIMIZED are specified, the 
window is created in a maximized state. 


XYF_INVISIBLE Create the window initially invisible. 
XYF_MAXIMIZED Show the window initially maximized. 
XYF_MINIMIZED Show the window initially iconic. — 


XYF_NOAUTOCLOSE Do not close the window automatically when the VIO 
application terminates. This parameter is ignored unless the 
program is a VIO-windowed application. 

XYF_NORMAL Create the window visible, with a size and position as 

specified. This is the default. 
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Appendix B. Error Codes 


This section lists PM errors returned by WinGetLastError in order of their error numbers. For: 
explanations of these errors, see Appendix C, “Error Explanations” on page C-1. 


Error Number Error Constant 


0x0000 PMERR_OK 

0x0836 NERR_NetNotStarted 

0x0845 NERR_RedirectedPath 

0x084B NERR_BufTooSmall 

0x085E NERR_InvalidAPI 

0x0866 NERR_QNotFound 

0x0867 NERR_JobNotFound 

0x0868 NERR_DestNotFound 

0x0869 NERR_DestExists 

0x086A NERR_QExists 

0x086B NERR_QNoRoom 

0x086C NERR_JobNoRoom 

0x086D NERR_DestNoRoom 

O0x086E NERR_Destidle 

Ox086F NERR_DestinvalidOp 

0x0871 NERR_SpoolerNotLoaded 

0x0872 NERR_DestinvalidState 

0x0874 NERR_JobinvalidState 

0x0875 NERR_SpoolNoMemory 

0x0876 NERR_DriverNotFound 

0x0877 NERR_DataTypeinvalid 

0x0878 NERR_ProcNotFound 

0x0925 NERR_BadDev 

0x0927 NERR_CommDevinUse 

0x092F NERR_InvalidComputer 

0x0961 NERR_OpenFiles 

0x0965 NERR_LocalDrive 

0x1001 PMERR_INVALID_HWND 

0x1001 HMERR_NO_FRAME_WND_IN_CHAIN 
0x1002 PMERR_INVALID_HMQ 

0x1002 HMERR_INVALID_ASSOC_APP_WND 
0x1003 PMERR_PARAMETER_OUT_OF_RANGE 
0x1003 HMERR_INVALID_ASSOC_HELP_INST 
0x1004 PMERR_WINDOW_LOCK_UNDERFLOW 
0x1004 HMERR_INVALID_DESTROY_HELP_INST 
0x1005 PMERR_WINDOW_LOCK_OVERFLOW 
0x1005 HMERR_NO_HELP_INST_IN_CHAIN — 
0x1006 PMERR_BAD_WINDOW_LOCK_COUNT 
0x1006 HMERR_INVALID_HELP_INSTANCE_HDL 
0x1007 PMERR_WINDOW_NOT_LOCKED 
0x1007 HMERR_INVALID_QUERY_APP_WND 
0x1008 PMERR_INVALID_SELECTOR 
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0x1008 
0x1009 
0x1009 
0x100A 
0x100A 
0x100B 
0x100B 
0x100C 
0x100C 
0x100D 
0x100D 
0x100E 
0x100F 
0x1010 
0x1011 
0x1012 
0x1013 
0x1014 
0x1015 
0x1016 
0x1017 
0x1018 
0x1019 
0x101A 
-— 0x101B 
0x101C 
0x101D 
0x101E 
0x101F 
0x1020 
0x1021 
0x1034 
0x1035 
0x1036 
0x1037 
0x1038 
0x1039 
0x103A 
0x103B 
0x103C 
0x103D 
0x103E 
0x103F 
0x1040 
0x1041 
0x1042 
0x1043 
0x1044 


HMERR_HELP_INST_CALLED_INVALID 
PMERR_CALL_FROM_WRONG_THREAD 
HMERR_HELPTABLE_UNDEFINE 
PMERR_RESOURCE_NOT_FOUND 
HMERR_HELP_INSTANCE_UNDEFINE 
PMERR_INVALID_STRING_PARM 
HMERR_HELPITEM_NOT_FOUND 
PMERR_INVALID_HHEAP 
HMERR_INVALID_ HELPSUBITEM_ SIZE 
PMERR_INVALID_HEAP_ POINTER 
HMERR_HELPSUBITEM_NOT_FOUND 
PMERR_INVALID_HEAP_SIZE_PARM 
PMERR_INVALID_HEAP_ SIZE 
PMERR_INVALID_HEAP_SIZE_WORD 
PMERR_HEAP_OUT_OF_MEMORY 
PMERR_HEAP_MAX_SIZE_REACHED 
PMERR_INVALID_HATOMTBL 
PMERR_INVALID_ATOM 
PMERR_INVALID_ATOM_NAME 
PMERR_INVALID_INTEGER_ATOM 
PMERR_ATOM. NAME_NOT_FOUND 
PMERR_QUEUE_TOO LARGE 
PMERR_INVALID_FLAG 
PMERR_INVALID_HACCEL 
PMERR_INVALID_HPTR 
PMERR_INVALID_HENUM 
PMERR_INVALID_SRC_CODEPAGE 
PMERR_INVALID_DST_CODEPAGE 
PMERR_UNKNOWN_COMPONENT_ID 
PMERR_UNKNOWN_ERROR_CODE 
PMERR_SEVERITY_LEVELS 
PMERR_INVALID_RESOURCE_FORMAT 
WINDBG_WINDOW_UNLOCK_WAIT 
PMERR_NO_MSG_QUEUE 
PMERR_WIN_DEBUGMSG 
PMERR_QUEUE_FULL 
PMERR_LIBRARY_LOAD FAILED 
PMERR_PROCEDURE_LOAD FAILED 
PMERR. LIBRARY_DELETE_FAILED | 
PMERR_PROCEDURE_DELETE_FAILED 
PMERR_ARRAY_TOO_LARGE 
PMERR_ARRAY TOO SMALL 
PMERR_DATATYPE_ENTRY_BAD_INDEX 
PMERR_DATATYPE_ENTRY_CTL_BAD 
PMERR_DATATYPE_ENTRY_CTL_MISS 
PMERR_DATATYPE_ENTRY_INVALID 
PMERR_DATATYPE_ENTRY_NOT_NUM 
PMERR_DATATYPE_ENTRY_NOT_OFF 
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0x1045 
0x1046 
0x1047 
0x1048 
0x1049 
0x104A 
0x104D 
0x104E 
0x104F 
0x1050 
0x1051 

0x1052 
0x1055 
0x1056 
0x1057 
0x1058 
0x1059 
0x1101 

0x1102 
0x1103 
0x1104 
0x1105 
0x1106 
0x1107 
0x1108 
0x1109 
0x110A 
0x110B 
0x110C 
0x110D 
0x110E 
0x110F 
0x1110 
0x1111 

0x1112 
0x1113 
0x1114 
0x1115 
0x1116 
0x1117 
0x1118 
0x1119 
Ox111A 
0x111B 
0x111C 
0x111D 
Ox111E 
0x111F 


PMERR_DATATYPE_INVALID 
PMERR_DATATYPE_NOT_UNIQUE 
PMERR_DATATYPE_TOO LONG 
PMERR_DATATYPE_TOO_SMALL 
PMERR_DIRECTION_ INVALID 
PMERR_INVALID_HAB 
PMERR_INVALID_ HSTRUCT 
PMERR_LENGTH_ TOO SMALL 
PMERR_MSGID_TOO_ SMALL 
PMERR_NO_HANDLE_ALLOC 
PMERR_NOT_IN A PM SESSION 
PMERR_MSG_QUEUE_ALREADY_EXISTS 
PMERR_OLD_ RESOURCE 
PMERR_WPDSERVER_IS_ACTIVE 
PMERR_WPDSERVER_NOT_STARTED 
PMERR_SOMDD_IS_ACTIVE 
PMERR_SOMDD_NOT_STARTED 
PMERR_INVALID PIB 
PMERR_INSUFF_SPACE_TO_ADD 
PMERR_INVALID_GROUP_HANDLE 
PMERR_DUPLICATE_TITLE 
PMERR_INVALID_TITLE 
PMERR_INVALID_ TARGET HANDLE 
PMERR_HANDLE_NOT_IN_GROUP 
PMERR_INVALID_PATH_STATEMENT 
PMERR_NO_PROGRAM FOUND 
PMERR_INVALID_BUFFER_SIZE 
PMERR_BUFFER_TOO_SMALL 
PMERR_PL_INITIALISATION_FAIL 
PMERR_CANT_DESTROY_SYS_GROUP 
PMERR_INVALID_TYPE_CHANGE 
PMERR_INVALID_PROGRAM_HANDLE 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_INVALID_CIRCULAR_REF 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_TASK_HEADER_TOO BIG 
PMERR_INVALID_INI_FILE_HANDLE 
PMERR_MEMORY_SHARE 
PMERR_OPEN_QUEUE 
PMERR_CREATE_QUEUE 
PMERR_WRITE_QUEUE 
PMERR_READ_QUEUE 


~ PMERR_CALL_NOT_EXECUTED 


PMERR_UNKNOWN_ APIPKT 
PMERR_INITHREAD_ EXISTS 
PMERR_CREATE_THREAD 
PMERR_NO_HK_PROFILE_INSTALLED 
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0x1120 
0x1121 

0x1122 
0x1123 
0x1124 
0x1125 
0x1126 
0x1127 
0x1128 
0x1129 
0x112A 
0x112B 
0x112C 
0x112D 
0x112E 
0x112F 
0x1130 
0x1131 

0x1132 
0x1133 
0x1134 
0x1135 
0x1136 
0x1200 
0x1201 

0x1202 
0x1203 
0x1204 
0x1205 
0x1206 
0x1207 
0x1208 
0x1208 
0x1209 
0x120A 
0x120B 
0x120C 
0x120D 
0x120E 
0x1301 

0x1302 

0x1303 
0x1304 
0x1305 
0x1306 
0x1307 
0x1308 
0x1309 


PMERR_INVALID_DIRECTORY 
PMERR_WILDCARD_IN_FILENAME 
PMERR_FILENAME_BUFFER_FULL 
PMERR_FILENAME_TOO_LONG 
PMERR_INI_FILE_IS SYS OR_USER 
PMERR_BROADCAST_PLMSG 
PMERR_190_INIT_DONE 
PMERR_HMOD_FOR_PMSHAPI 
PMERR_SET_HK_ PROFILE 


~ PMERR_API_NOT_ALLOWED 


PMERR_INI_STILL_OPEN 
PMERR_PROGDETAILS NOT_IN_INI 
PMERR_PIBSTRUCT_NOT_IN_INI 
PMERR_INVALID_DISKPROGDETAILS — 
PMERR_PROGDETAILS_READ_ FAILURE 
PMERR_PROGDETAILS WRITE_FAILURE 
PMERR_PROGDETAILS QSIZE_FAILURE 
PMERR_INVALID_PROGDETAILS 
PMERR_SHEPROFILEHOOK_NOT_FOUND 
PMERR_190PLCONVERTED 
PMERR_FAILED_TO_CONVERT_INI_PL 
PMERR_PMSHAPI_NOT_INITIALISED 
PMERR_INVALID_SHELL_API_HOOK_ID 
PMERR_DOS_ ERROR 
PMERR_NO_SPACE 
PMERR_INVALID_SWITCH_HANDLE 
PMERR_NO_ HANDLE 
PMERR_INVALID_ PROCESS _ID 
PMERR_NOT_SHELL 

PMERR_INVALID_ WINDOW 
PMERR_INVALID_POST_MSG 
PMERR_INVALID_ PARAMETERS 
PMERR_INVALID_ PARAMETERS 
PMERR_INVALID_ PROGRAM_TYPE 
PMERR_NOT_EXTENDED_FOCUS 
PMERR_INVALID_SESSION_ID 
PMERR_SMG_INVALID_ICON_FILE 
PMERR_SMG_ICON_NOT_CREATED 
PMERR_SHL_DEBUG 
PMERR_OPENING_INI_FILE 
PMERR_INI_FILE_CORRUPT 
PMERR_INVALID_PARM 
PMERR_NOT_IN_IDX 
PMERR_NO_ENTRIES_IN_GROUP 
PMERR_INI_WRITE_FAIL 
PMERR_IDX_FULL 
PMERR_INI_PROTECTED 
PMERR_MEMORY_ALLOC 
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0x130A 
0x130B 
0x130C 
0x130D 
0x130D 
0x1401 

0x1402 

0x1403 
0x1405 
0x1406 
0x1407 
0x1408 
0x1409 
0x140A 
0x140B 
0x140C 
0x140D 
0x140E 
0x140F 
0x1501 

0x1502 
0x1503 
0x1504 
0x1505 
0x1506 
0x1507 
0x1508 
0x1509 
0x150B 
0x150C 
0x150D 
0x150E 
0x150F 
Ox151F 
0x152F 
0x1530 
0x1531 

0x1532 
0x1533 
0x1534 
0x1601 

0x1602 
0x1603 
0x1604 
0x1605 
0x1606 
0x1607 
0x1608 


PMERR_INI_INIT_ALREADY_DONE 
PMERR_INVALID_INTEGER 
PMERR_INVALID_ASCIIZ 
PMERR_CAN_NOT_CALL_SPOOLER 
PMERR_VALIDATION_REJECTED 
PMERR_WARNING_WINDOW_NOT_KILLED 
PMERR_ERROR_INVALID_WINDOW 
PMERR_ALREADY_INITIALIZED 
PMERR_MSG_PROG_NO_MOU 
PMERR_MSG_PROG_NON_RECOV 
PMERR_WINCONV_INVALID_PATH 
PMERR_Pl_NOT_INITIALISED 
PMERR_PL_NOT_INITIALISED 
PMERR_NO_TASK_MANAGER 
PMERR_SAVE_NOT_IN PROGRESS 
PMERR_NO_STACK_SPACE 
PMERR_INVALID_COLR_FIELD 
PMERR_INVALID_COLR_VALUE 
PMERR_COLR_WRITE 
PMERR_TARGET_FILE_EXISTS 
PMERR_SOURCE_SAME_AS_ TARGET 
PMERR_SOURCE_FILE_NOT_FOUND 
PMERR_INVALID_NEW_PATH 
PMERR_TARGET_FILE_NOT_FOUND 
PMERR_INVALID_DRIVE_NUMBER 
PMERR_NAME_TOO_LONG 
PMERR_NOT_ENOUGH_ROOM_ON _DISK 
PMERR_NOT_ENOUGH_MEM 
PMERR_LOG_DRV_DOES_NOT_EXIST 
PMERR_INVALID_DRIVE 
PMERR_ACCESS_DENIED 
PMERR_NO_FIRST_SLASH 
PMERR_READ_ ONLY_FILE 
PMERR_GROUP_PROTECTED 
PMERR_INVALID_ PROGRAM_CATEGORY 
PMERR_INVALID_APPL 
PMERR_CANNOT_START 
PMERR_STARTED_IN_BACKGROUND 
PMERR_INVALID_HAPP 
PMERR_CANNOT_STOP 
PMERR_INTERNAL_ERROR_1 
PMERR_INTERNAL_ERROR_2 
PMERR_INTERNAL_ERROR_3 
PMERR_INTERNAL_ERROR_4 
PMERR_INTERNAL_ERROR_5 
PMERR_INTERNAL_ERROR_6 
PMERR_INTERNAL_ERROR_7 
PMERR_INTERNAL_ERROR_8 
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0x1609 PMERR_INTERNAL_ERROR_9 


0x160A PMERR_INTERNAL_ERROR_10 

0x160B PMERR_INTERNAL_ERROR_11 

0x160C PMERR_INTERNAL_ERROR_12 

0x160D PMERR_INTERNAL_ERROR_13 

0x160E PMERR_INTERNAL_ERROR_14 

0x160F - PMERR_INTERNAL_ERROR_15 

0x1610 PMERR_INTERNAL_ERROR_16 

0x1611 PMERR_INTERNAL_ERROR_17 

0x1612 PMERR_INTERNAL_ERROR_18 

0x1613 PMERR_INTERNAL_ERROR_19 

0x1614 PMERR_INTERNAL_ERROR_20 

0x1615 PMERR_INTERNAL_ERROR_21 

0x1616 PMERR_INTERNAL_ERROR_22 

0x1617 PMERR_INTERNAL_ERROR_23 

0x1618 PMERR_INTERNAL_ERROR_24 

0x1619 PMERR_INTERNAL_ERROR_25 

Ox161A PMERR_INTERNAL_ERROR_26 

0x161B PMERR_INTERNAL_ERROR_27 

0x161C PMERR_INTERNAL_ERROR_28 

0x161D PMERR_INTERNAL_ERROR_29 

0x1630 PMERR_INVALID_FREE_MESSAGE_ID 
0x1641 PMERR_FUNCTION_NOT_SUPPORTED 
0x1642 PMERR_INVALID_ARRAY_COUNT 
0x1643 PMERR_INVALID_LENGTH 

0x1644 PMERR_INVALID_BUNDLE_TYPE 
0x1645 PMERR_INVALID_ PARAMETER 

0x1646 PMERR_INVALID_NUMBER_OF_PARMS 
0x1647 PMERR_GREATER_THAN 64K 

0x1648 PMERR_INVALID_PARAMETER_TYPE 
0x1649 PMERR_NEGATIVE_STRCOND_DIM 
0x164A PMERR_INVALID_ NUMBER_OF_TYPES 
0x164B PMERR_INCORRECT_HSTRUCT 
0x164C PMERR_INVALID_ ARRAY_SIZE 

0x164D PMERR_INVALID_CONTROL_DATATYPE 
0x164E PMERR_INCOMPLETE_CONTROL_SEQU 
0x164F PMERR_INVALID_ DATATYPE 

0x1650 PMERR_INCORRECT_DATATYPE 
0x1651 PMERR_NOT_SELF_DESCRIBING_DTYP 
0x1652 - PMERR_INVALID_CTRL_SEQ_INDEX 
0x1653 PMERR_INVALID_TYPE_FOR_LENGTH 
0x1654 PMERR_INVALID_TYPE_FOR_OFFSET 
0x1655 PMERR_INVALID_ TYPE_FOR_MPARAM 
0x1656 PMERR_INVALID_MESSAGE_ID 

0x1657 PMERR_C_LENGTH_TOO_ SMALL 
0x1658 PMERR_APPL_STRUCTURE_TOO_SMALL 
0x1659 PMERR_INVALID_ERRORINFO_HANDLE 


0x165A PMERR_INVALID_-CHARACTER_INDEX 
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0x1700 
0x1701 
0x1702 
0x1703 
0x1704 
0x1705 
0x1706 
0x1707 
0x1708 
0x1709 
0x170A 
0x170B 
0x170C 
0x170D 
0x170E 
0x170F 
0x1710 
0x1711 
0x1712 
0x1713 
0x1714 
0x1715 
0x1716 
0x1717 
0x1718 
0x1719 
0x1720 
0x1721 
0x1F00 
0x2001 
0x2001 
0x2002 
0x2002 
0x2003 
0x2003 
0x2004 
0x2004 
0x2005 
0x2005 
0x2006 
0x2006 
0x2007 
0x2007 
0x2008 
0x2008 
- 0x2009 
0x2009 
0x200A 


WPERR_PROTECTED_CLASS 
WPERR_INVALID_CLASS 
WPERR_INVALID_SUPERCLASS 
WPERR_NO_MEMORY 
WPERR_SEMAPHORE_ERROR 
WPERR_BUFFER_TOO_SMALL 
WPERR_CLSLOADMOD_FAILED 
WPERR_CLSPROCADDR_FAILED 
WPERR_OBJWORD_LOCATION 
WPERR_INVALID_ OBJECT 
WPERR_MEMORY_CLEANUP 
WPERR_INVALID_ MODULE 
WPERR_INVALID_OLDCLASS 
WPERR_INVALID_NEWCLASS 
WPERR_NOT_IMMEDIATE_CHILD 
WPERR_NOT_WORKPLACE_CLASS 
WPERR_CANT_REPLACE_METACLS 
WPERR_INI_FILE_WRITE 
WPERR_INVALID_ FOLDER 
WPERR_BUFFER_OVERFLOW 
WPERR_OBJECT_NOT_FOUND 
WPERR_INVALID_HFIND 
WPERR_INVALID_ COUNT 
WPERR_INVALID_ BUFFER 
WPERR_ALREADY_EXISTS 
WPERR_INVALID_FLAGS 
WPERR_INVALID_OBJECTID 
WPERR_ INVALID. TARGET_OBJECT 
PMERR_NOT_DRAGGING 
PMERR_ALREADY_IN_AREA 
HMERR_INDEX_NOT_FOUND 
PMERR_ALREADY_IN_ELEMENT 
HMERR_CONTENT_NOT_FOUND 
PMERR_ALREADY_IN_PATH 
HMERR_OPEN_LIB_FILE 
PMERR_ALREADY_IN_SEG 
HMERR_READ LIB FILE 
PMERR_AREA_INCOMPLETE 


-HMERR_CLOSE LIB FILE 


PMERR_BASE_ERROR 
HMERR_INVALID_LIB_FILE 
PMERR_BITBLT_LENGTH_EXCEEDED 
HMERR_NO_MEMORY 
PMERR_BITMAP_IN_USE 
HMERR_ALLOCATE_SEGMENT 
PMERR_BITMAP_IS_SELECTED 
HMERR_FREE_MEMORY 
PMERR_BITMAP_NOT_FOUND 
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0x200B PMERR_BITMAP_NOT_SELECTED 


0x200C PMERR_BOUNDS OVERFLOW 
0x200D PMERR_CALLED_SEG_IS_ CHAINED 
0x200E PMERR_CALLED SEG _IS_ CURRENT 
0x200F PMERR_CALLED_SEG_NOT_FOUND 
0x2010 PMERR_CANNOT_DELETE_ALL_DATA 
0x2010 HMERR_PANEL_NOT_FOUND 

0x2011 PMERR_CANNOT_REPLACE_ELEMENT_0 
0x2011 HMERR_DATABASE_NOT_OPEN | 
0x2012 PMERR_COL_TABLE_NOT_REALIZABLE 
0x2013 PMERR_COL_TABLE_NOT_ REALIZED 
0x2013 HMERR LOAD DLL ~ 

0x2014 PMERR_COORDINATE_OVERFLOW 
0x2015 PMERR_CORR_FORMAT_MISMATCH 
0x2016 PMERR_DATA_TOO LONG 

0x2017 PMERR_DC_IS ASSOCIATED 

0x2018 PMERR_DESC_STRING_TRUNCATED 
0x2019 PMERR_DEVICE_DRIVER_ERROR_1 
0x201A PMERR_DEVICE_DRIVER ERROR 2 
0x201B PMERR_DEVICE_DRIVER_ERROR 3 
0x201C PMERR_DEVICE_DRIVER_ERROR 4 
0x201D - PMERR_DEVICE_DRIVER_ERROR_5 
0x201E PMERR_DEVICE_DRIVER_ERROR 6 
0x201F PMERR_DEVICE_DRIVER_ERROR _7- 

- 0x2020 PMERR_DEVICE_DRIVER_ERROR_8 
0x2021 PMERR_DEVICE_DRIVER_ERROR_9 
0x2022 PMERR_DEVICE_DRIVER_ERROR_10 
0x2023 PMERR_DEV_FUNC_NOT_INSTALLED 
0x2024 PMERR_DOSOPEN_FAILURE 
0x2025 PMERR_DOSREAD_FAILURE 
0x2026 PMERR_DRIVER_NOT_FOUND 
0x2027 PMERR_DUP_SEG 
0x2028 PMERR_DYNAMIC_SEG SEQ ERROR 
0x2029 PMERR_DYNAMIC_SEG_ZERO_INV 
0x202A PMERR_ELEMENT_INCOMPLETE 
0x202B PMERR_ESC_CODE_NOT_SUPPORTED 
0x202C PMERR_EXCEEDS_MAX_SEG_LENGTH 
0x202D PMERR_FONT_AND MODE_MISMATCH 
0x202E PMERR_FONT_FILE_NOT_LOADED 
0x202F PMERR_FONT_NOT_LOADED 
0x2030 PMERR_FONT TOO BIG 
0x2031 PMERR_HARDWARE_INIT_FAILURE 
0x2032 PMERR_HBITMAP_BUSY 
0x2033 PMERR_HDC_BUSY 
0x2034 PMERR_HRGN_BUSY 
0x2035 PMERR_HUGE_FONTS_NOT_SUPPORTED 
0x2036 PMERR_ID_HAS_NO_ BITMAP 
0x2037 PMERR_IMAGE_INCOMPLETE 
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0x2038 
0x2039 
0x203A 
0x203B 
0x203C 
0x203D 
0x203E 
Ox203F 
0x2040 
0x2041 
0x2042 
0x2043 
0x2044 
0x2045 
0x2046 
0x2047 
0x2048 
0x2049 
0x204A 
0x204B 
0x204C 
0x204D 
0x204E 
0x204F 
0x2050 
0x2051 
0x2052 
0x2053 
0x2054 
0x2055 
0x2056 
0x2057 
0x2058 
0x2059 
0x205A 
0x205B 
0x205C 
0x205D 
0x205E 
0x205F 
0x2060 
0x2061 
0x2062 
0x2063 
0x2064 
0x2065 
0x2066 
0x2067 


PMERR_INCOMPAT_COLOR_FORMAT 
PMERR_INCOMPAT_COLOR_OPTIONS 


-PMERR_INCOMPATIBLE_BITMAP 


PMERR_INCOMPATIBLE_METAFILE 
PMERR_INCORRECT_DC_TYPE 
PMERR_INSUFFICIENT_DISK_SPACE 
PMERR_INSUFFICIENT_ MEMORY 
PMERR_INV_ANGLE_PARM 
PMERR_INV_ARC_CONTROL 
PMERR_INV_AREA_ CONTROL 
PMERR_INV_ARC_ POINTS 
PMERR_INV_ATTR_MODE 
PMERR_INV_BACKGROUND_COL_ATTR 
PMERR_INV_BACKGROUND_MIX_ATTR 
PMERR_INV_BITBLT_MIX 
PMERR_INV_BITBLT_STYLE 
PMERR_INV_BITMAP_DIMENSION 
PMERR_INV_BOX_CONTROL 
PMERR_INV_BOX_ROUNDING_PARM 
PMERR_INV_CHAR_ANGLE_ATTR 


-PMERR_INV_CHAR_DIRECTION_ATTR 


PMERR_INV_CHAR_MODE_ATTR 
PMERR_INV_CHAR_POS OPTIONS 
PMERR_INV_CHAR_SET_ATTR 
PMERR_INV_CHAR_SHEAR_ATTR 
PMERR_INV_CLIP_PATH_OPTIONS 
PMERR_INV_CODEPAGE 
PMERR_INV_COLOR_ATTR 
PMERR_INV_COLOR DATA 
PMERR_INV_COLOR_FORMAT 
PMERR_INV_COLOR_INDEX 
PMERR_INV_COLOR_ OPTIONS 
PMERR_INV_COLOR_START_INDEX 
PMERR_INV_COORD_OFFSET 
PMERR_INV_COORD_SPACE 
PMERR_INV_COORDINATE 
PMERR_INV_CORRELATE_DEPTH 
PMERR_INV_CORRELATE_TYPE 
PMERR_INV_CURSOR_BITMAP 
PMERR_INV_DC_DATA 
PMERR_INV_DC_TYPE 
PMERR_INV_DEVICE_NAME 
PMERR_INV_DEV_MODES OPTIONS 
PMERR_INV_DRAW_CONTROL 
PMERR_INV_DRAW_VALUE 
PMERR_INV_DRAWING_MODE 
PMERR_INV_DRIVER_DATA 
PMERR_INV_DRIVER_NAME 
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0x2068 — 


0x2069 
Ox206A 
0x206B 
0x206C 
0x206D 
Ox206E 
Ox206F 
0x2070 
0x2071 

0x2072 
0x2073 
0x2074 
0x2075 
0x2076 
0x2077 
0x2078 
0x2079 
0x207A 
0x207B 
0x207C 
0x207D 
0x207E 
0x207F 
0x2080 
0x2081 

0x2082 
0x2083 
0x2084 
0x2085 
0x2086 
0x2087 
0x2088 
0x2089 
0x208A 
0x208B 
0x208C 
0x208D 
0x208E 
0x208F 
0x2090 
0x2091 

0x2092 
0x2093 
0x2094 
0x2095 
0x2096 
0x2097 


PMERR_INV_DRAW_BORDER_OPTION 
PMERR_INV_EDIT_MODE 
PMERR_INV_ELEMENT_OFFSET 
PMERR_INV_ELEMENT_POINTER 
PMERR_INV_END_PATH_ OPTIONS 
PMERR_INV_ESC_CODE 
PMERR_INV_ESCAPE_DATA 
PMERR_INV_EXTENDED_LCID 
PMERR_INV_FILL_PATH OPTIONS 
PMERR_INV_FIRST_CHAR 
PMERR_INV_FONT ATTRS 
PMERR_INV_FONT_FILE DATA 
PMERR_INV_FOR_THIS DC_TYPE 
PMERR_INV_FORMAT_CONTROL 


-PMERR_INV_FORMS_CODE 


PMERR_INV_FONTDEF 
PMERR_INV_GEOM_LINE_WIDTH_ATTR 
PMERR_INV_GETDATA_CONTROL 
PMERR_INV_GRAPHICS FIELD 
PMERR_INV_HBITMAP 
PMERR_INV_HDC 
PMERR_INV_HJOURNAL 
PMERR_INV_HMF 
PMERR_INV_HPS 
PMERR_INV_HRGN 
PMERR_INV_ID 
PMERR_INV_IMAGE_DATA_LENGTH 
PMERR_INV_IMAGE_DIMENSION 
PMERR_INV_IMAGE_FORMAT 
PMERR_INV_IN_AREA 
PMERR_INV_IN_ CALLED SEG 
PMERR_INV_IN_CURRENT_EDIT_MODE 
PMERR_INV_IN_DRAW_MODE 
PMERR_INV_IN_ELEMENT 
PMERR_INV_IN_IMAGE 
PMERR_INV_IN_PATH 
PMERR_INV_IN_RETAIN_ MODE 
PMERR_INV_IN_SEG 
PMERR_INV_IN_VECTOR_SYMBOL 
PMERR_INV_INFO_TABLE . 
PMERR_INV_JOURNAL_OPTION 
PMERR_INV_KERNING_FLAGS 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_LINE_END_ATTR 
PMERR_INV_LINE JOIN _ATTR 
PMERR_INV_LINE_TYPE_ATTR 
PMERR_INV_LINE_WIDTH_ATTR 
PMERR_INV_LOGICAL_ADDRESS 
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0x2098 
0x2099 
0x209A 
0x209B 
0x209C 
0x209D 
0x209E 
0x209F 
0x20A0 
Ox20A1 
0x20A2 
0x20A3 
0x20A4 
0x20A5 
Ox20A6 
0x20A7 
0x20A8 
0x20A9 
0x20AA 
0x20AB 
0x20AC 
0x20AD 
0Ox20AE 
Ox20AF 
0x20B0 
0x20B1 
0x20B2 
0x20B3 
0x20B4 
0x20B5 
0x20B6 
0x20B7 
0x20B8 
0x20B9 
0x20BA 
0x20BB 
0x20BC 
0x20BD 
0x20BE 
Ox20BF 
0x20C0 
0x20C1 
0x20C2 
0x20C3 
0x20C4 
0x20C5 
0x20C6 
0x20C7 


PMERR_INV_MARKER_BOX_ATTR 
PMERR_INV_MARKER_SET_ATTR 
PMERR_INV_MARKER_SYMBOL_ATTR 
PMERR_INV_MATRIX_ELEMENT 
PMERR_INV_MAX_HITS 
PMERR_INV_METAFILE 
PMERR_INV_METAFILE_LENGTH 
PMERR_INV_METAFILE OFFSET 
PMERR_INV_MICROPS_DRAW_CONTROL 
PMERR_INV_MICROPS_FUNCTION 
PMERR_INV_MICROPS_ORDER 
PMERR_INV_MIX_ATTR 
PMERR_INV_MODE_FOR_OPEN_DYN 
PMERR_INV_MODE_FOR REOPEN SEG 
PMERR_INV_MODIFY_PATH_ MODE 
PMERR_INV_MULTIPLIER 
PMERR_INV_NESTED_ FIGURES 
PMERR_INV_OR_INCOMPAT_OPTIONS 
PMERR_INV_ORDER_LENGTH 
PMERR_INV_ORDERING_PARM 
PMERR_INV_OUTSIDE_DRAW_MODE 
PMERR_INV_PAGE_VIEWPORT 
PMERR_INV_PATH_ID 
PMERR_INV_PATH_MODE 
PMERR_INV_PATTERN_ATTR 
PMERR_INV_PATTERN_REF_PT_ATTR 
PMERR_INV_PATTERN_SET_ATTR 
PMERR_INV_PATTERN_SET FONT 
PMERR_INV_PICK_APERTURE_OPTION 
PMERR_INV_PICK_APERTURE_POSN 
PMERR_INV_PICK_APERTURE_SIZE 
PMERR_INV_PICK_NUMBER 
PMERR_INV_PLAY_METAFILE_OPTION 
PMERR_INV_PRIMITIVE_TYPE 
PMERR_INV_PS_SIZE 
PMERR_INV_PUTDATA_FORMAT 
PMERR_INV_QUERY_ELEMENT_NO_ 
PMERR_INV_RECT 
PMERR_INV_REGION_CONTROL 
PMERR_INV_REGION_MIX_MODE 
PMERR_INV_REPLACE_MODE_FUNC 
PMERR_INV_RESERVED_FIELD 
PMERR_INV_RESET_OPTIONS 
PMERR_INV_RGBCOLOR 
PMERR_INV_SCAN_START 
PMERR_INV_SEG ATTR 
PMERR_INV_SEG_ATTR_VALUE 
PMERR_INV_SEG_CH LENGTH 
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0x20C8 
0x20C9 
0x20CA 
0x20CB 
0x20CC 
0x20CD 
0x20CE 
Ox20CF 
0x20D0 
0x20D1 
0x20D2 
0x20D3 
0x20D4 
0x20D5 
0x20D6 
0x20D7 
0x20D8 
0x20D9 
Ox20DA 
0x20DB 
0x20DC 
0x20DD 
0x20DE 
Ox20DF 
0x20E0 
0x20E1 
Ox20E2 
0x20E3 
Ox20E4 
0x20E5 
Ox20E6 
0x20E7 
Ox20E8 
0x20E9 
Ox20EA 
0x20EB 
Ox20EC 
Ox20ED 
Ox20EE 
Ox20EF 
Ox20F0 
Ox20F1 
Ox20F2 
Ox20F3 
Ox20F4 
Ox20F5 
Ox20F6 
Ox20F7 


PMERR_INV_SEG_NAME 
PMERR_INV_SEG_OFFSET 
PMERR_INV_SETID 
PMERR_INV_SETID_TYPE 
PMERR_INV_SET_VIEWPORT_OPTION 
PMERR_INV_SHARPNESS_PARM 
PMERR_INV_SOURCE_OFFSET 
PMERR_INV_STOP_DRAW_VALUE 
PMERR_INV_TRANSFORM_TYPE 
PMERR_INV_USAGE_PARM 
PMERR_INV_VIEWING_LIMITS 
PMERR_JFILE_BUSY 
PMERR_JNL_FUNC_DATA_TOO_LONG 
PMERR_KERNING_NOT_SUPPORTED 
PMERR_LABEL_NOT_FOUND 
PMERR_MATRIX_OVERFLOW 
PMERR_METAFILE_INTERNAL_ERROR 
PMERR_METAFILE_IN_USE 
PMERR_METAFILE_LIMIT_EXCEEDED 
PMERR_NAME_STACK_FULL 
PMERR_NOT_CREATED BY_DEVOPENDC 
PMERR_NOT_IN AREA 
PMERR_NOT_IN_DRAW_MODE 
PMERR_NOT_IN_ELEMENT 
PMERR_NOT_IN_IMAGE 
PMERR_NOT_IN PATH 
PMERR_NOT_IN_RETAIN MODE 
PMERR_NOT_IN SEG 
PMERR_NO_BITMAP_SELECTED 
PMERR_NO_CURRENT_ELEMENT 
PMERR_NO_ CURRENT _SEG 
PMERR_NO. METAFILE_RECORD_HANDLE 
PMERR_ORDER_TOO BIG 
PMERR_OTHER_SET_ID_REFS 
PMERR_OVERRAN_SEG 
PMERR_OWN_SET_ID_REFS 
PMERR_PATH_INCOMPLETE 
PMERR_PATH_LIMIT_EXCEEDED 
PMERR_PATH_UNKNOWN 
PMERR_PEL_IS_CLIPPED 
PMERR_PEL_NOT_AVAILABLE 
PMERR_PRIMITIVE_STACK_EMPTY 
PMERR_PROLOG_ERROR 
PMERR_PROLOG_SEG_ATTR_NOT_SET 
PMERR_PS_BUSY 
PMERR_PS IS ASSOCIATED 
PMERR_RAM_JNL_FILE_TOO_ SMALL 
PMERR_REALIZE_NOT_SUPPORTED 
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0x20F8 
0x20F9 
Ox20FA 
0x20FB 
0x20FC 
0x20FD 
0x20FE 
Ox20FF 
0x2100 
0x2101 

0x2102 
0x2103 
0x2104 
0x2105 
0x2106 
0x2107 
0x2108 


0x2109 — 


0x210A 
0x210B 
0x210C 
0x210D 
0x210E 
0x210F 
0x2110 
0x2111 

0x2112 
0x2113 
0x2114 
0x2115 
0x2116 
0x2117 
0x2118 
0x2119 
0x2120 
0x2120 
0x3001 

0x3002 
0x3003 
0x3004 
0x3005 
0x3006 
0x3007 
0x3008 
0x3009 
0x300A 
0x300B 
0x300C 


PMERR_REGION_IS_CLIP_REGION 
PMERR_RESOURCE_DEPLETION 
PMERR_SEG_AND_REFSEG ARE SAME 
PMERR_SEG_CALL_RECURSIVE 
PMERR_SEG CALL_STACK_EMPTY 
PMERR_SEG_CALL_STACK_FULL 
PMERR_SEG_IS_CURRENT 
PMERR_SEG_NOT_CHAINED 
PMERR_SEG NOT FOUND 
PMERR_SEG_STORE_LIMIT_EXCEEDED 
PMERR_SETID_IN_USE 
PMERR_SETID_NOT_FOUND 
PMERR_STARTDOC_NOT_ISSUED 
PMERR_STOP_DRAW_OCCURRED 
PMERR_TOO_MANY_METAFILES_IN_USE 
PMERR_TRUNCATED_ORDER 
PMERR_UNCHAINED_SEG_ZERO_INV 
PMERR_UNSUPPORTED_ATTR 
PMERR_UNSUPPORTED_ATTR_VALUE 
PMERR_ENDDOC_NOT_ISSUED 
PMERR_PS_NOT_ASSOCIATED 
PMERR_INV_FLOOD FILL_OPTIONS 
PMERR_INV_FACENAME 
PMERR_PALETTE_SELECTED 
PMERR_NO_PALETTE_SELECTED 
PMERR_INV_HPAL 
PMERR_PALETTE_BUSY 
PMERR_START_POINT_CLIPPED 
PMERR_NO FILL 
PMERR_INV_FACENAMEDESC 
PMERR_INV_BITMAP_DATA 
PMERR_INV_CHAR_ALIGN_ATTR 
PMERR_INV_HFONT 
PMERR_HFONT_IS_SELECTED 
PMERR_DRVR_NOT_SUPPORTED 
PMERR_RASTER_FONT 
HMERR_DDF_MEMORY 
HMERR_DDF_ALIGN_TYPE 
HMERR_DDF_BACKCOLOR 
HMERR_DDF_FORECOLOR 
HMERR_DDF_FONTSTYLE 
HMERR_DDF_REFTYPE 
HMERR_DDF_LIST_UNCLOSED 
HMERR_DDF_LIST_UNINITIALIZED 
HMERR_DDF_LIST_BREAKTYPE 
HMERR_DDF_LIST SPACING 
HMERR_DDF_HINSTANCE 
HMERR_DDF_EXCEED_MAX_LENGTH 
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0x300D HMERR_DDF_EXCEED_MAX_INC 


0x300E HMERR_DDF_INVALID_DDF 

0x300F HMERR_DDF_FORMAT. TYPE 

0x3010 HMERR_DDF_INVALID_PARM 

0x3011 HMERR_DDF_INVALID_FONT 

0x3012 HMERR_DDF_SEVERE 

0x4001 PMERR_SPL_DRIVER_ERROR 

0x4001 MERR_SPL_DRIVER_ERROR 

0x4002 PMERR_SPL_DEVICE_ERROR 

0x4002 MERR_SPL_DEVICE_ERROR 

0x4003 PMERR_SPL_DEVICE_NOT_INSTALLED 
0x4003 MERR_SPL_DEVICE_NOT_INSTALLED 
0x4004 PMERR_SPL_QUEUE_ERROR 

0x4004 MERR_SPL_QUEUE_ERROR 

0x4005 PMERR_SPL_INV_HSPL 

0x4005 MERR_SPL_INV_HSPL 

0x4006 PMERR_SPL_NO_DISK_SPACE 

0x4006 MERR_SPL_NO_DISK_SPACE 

0x4007 PMERR_SPL_NO_ MEMORY 

0x4007 MERR_SPL_NO_MEMORY 

0x4008 PMERR_SPL_PRINT_ ABORT 

0x4008 MERR_SPL_PRINT_ABORT 

0x4009 PMERR_SPL_SPOOLER_NOT_INSTALLED 
0x4009 MERR_SPL_SPOOLER_NOT_INSTALLED 
0x400A PMERR_SPL_INV_FORMS_CODE 
0x400A MERR_SPL_INV_FORMS_CODE 
0x400B PMERR_SPL_INV_PRIORITY 

0x400B MERR_SPL_INV_PRIORITY 

0x400C PMERR_SPL_NO FREE JOB _ID 
0x400C MERR_SPL_NO_FREE_JOB_ID 

0x400D PMERR_SPL_NO DATA 

0x400D MERR_SPL_NO_DATA 

0x400E PMERR_SPL_INV_TOKEN 

0x400E MERR_SPL_INV_TOKEN 

0x400F PMERR_SPL_INV_DATATYPE 

0x400F MERR_SPL_INV_DATATYPE 

0x4010 PMERR_SPL_PROCESSOR_ERROR 
0x4010 MERR_SPL_PROCESSOR_ERROR 
0x4011 PMERR_SPL_INV_JOB_ID 

0x4011 MERR_SPL_INV_JOB_ID 

0x4012 PMERR_SPL_JOB_NOT_PRINTING 
0x4012 MERR_SPL_JOB_NOT_PRINTING 
0x4013 PMERR_SPL_JOB_PRINTING 

0x4013 MERR_SPL_JOB_PRINTING 

0x4014 PMERR_SPL_QUEUE_ALREADY_EXISTS 
0x4014 _ MERR_SPL_QUEUE_ALREADY_EXISTS 
0x4015 PMERR_SPL_INV_QUEUE_NAME 
0x4015 MERR_SPL_INV_QUEUE_NAME 
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0x4016 
0x4016 
0x4017 
0x4017 
0x4018 
0x4018 
0x4019 
0x4019 
0x401A 
Ox401A 
0x401B 
0x401B 
0x401C 
0x401C 
0x401D 
0x401D 
0x401E 
0x401E 
0x401F 
0x401F 
0x4020 
0x4020 
0x4021 

0x4021 

0x4022 
0x4022 
0x4023 
0x4023 
0x4024 
0x4024 
0x4025 
0x4025 
0x4026 
0x4026 
0x4027 
0x4027 
0x4028 
0x4028 
0x4029 
0x4029 
0x402A 
0x402A 
0x402B 
0x402B 
0x402C 
0x402C 
0x402D 
0x402D 


PMERR_SPL_QUEUE_NOT_EMPTY 
MERR_SPL_QUEUE_NOT_EMPTY 
PMERR_SPL_DEVICE_ALREADY_EXISTS 
MERR_SPL_DEVICE_ALREADY_EXISTS 
PMERR_SPL_DEVICE_LIMIT_REACHED 
MERR_SPL_DEVICE_LIMIT_REACHED 
PMERR_SPL_STATUS_STRING_TRUNG 
MERR_SPL_STATUS_STRING_TRUNC 
PMERR_SPL_INV_LENGTH_OR_ COUNT 
MERR_SPL_INV_LENGTH_OR_COUNT 
PMERR_SPL_FILE_NOT_FOUND 
MERR_SPL_FILE_NOT_FOUND 
PMERR_SPL_CANNOT_OPEN_FILE 
MERR_SPL_CANNOT_OPEN FILE 
PMERR_SPL_DRIVER_NOT_INSTALLED 
MERR_SPL_DRIVER_NOT_INSTALLED 
PMERR_SPL_INV_PROCESSOR_DATTYPE 
MERR_ SPL_INV_PROCESSOR_DATTYPE 
PMERR_SPL_INV_DRIVER_DATATYPE 
MERR_SPL_INV_DRIVER_DATATYPE 
PMERR_SPL_PROCESSOR_NOT_INST 
MERR_SPL_PROCESSOR_NOT_INST 
PMERR_SPL_NO_SUCH_ LOG ADDRESS 
MERR_SPL_NO_SUCH_LOG_ ADDRESS 
PMERR_SPL_PRINTER_NOT FOUND 
MERR_SPL_PRINTER_NOT_FOUND 
PMERR_SPL_DD_NOT_FOUND 
MERR_SPL_DD_NOT_FOUND 
PMERR_SPL_QUEUE_NOT_FOUND 
MERR_SPL_QUEUE_NOT_FOUND 
PMERR_SPL_MANY_QUEUES ASSOC 
MERR_SPL_MANY_QUEUES ASSOC 
PMERR_SPL_NO_QUEUES ASSOCIATED 
MERR_SPL_NO_QUEUES ASSOCIATED 
PMERR_SPL_INI_FILE_ERROR 
MERR_SPL_INI_FILE_ERROR 
PMERR_SPL_NO_DEFAULT_QUEUE 
MERR_SPL_NO_DEFAULT_QUEUE 
PMERR_SPL_NO_CURRENT_FORMS_ CODE 
MERR_SPL_NO_CURRENT FORMS_CODE 
PMERR_SPL_NOT_AUTHORISED 
MERR_SPL_NOT_AUTHORISED 
PMERR_SPL_TEMP_NETWORK_ERROR 
MERR_SPL_TEMP_NETWORK_ERROR 
PMERR_SPL_HARD_NETWORK_ERROR 
MERR_SPL_HARD_NETWORK_ERROR 
PMERR_DEL_NOT_ALLOWED 
MERR_DEL_NOT_ALLOWED 
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0x402E 
0x402E 
0x402F 
0x402F 
0x4030 
0x4030 
0x4031 
0x4031 
0x4032 
0x4032 
0x4033 
0x4033 
0x4034 
0x4034 
0x4035 
0x4035 
0x4036 
0x4036 
0x4037 
0x4037 
0x4038 
0x4038 
0x4039 
~ 0x4039 
0x403A 
0x403A 
0x4040 
0x4040 
Ox4FC9 
Ox4FC9 
Ox4FCA 
Ox4FCA 
0x4FCB 
Ox4FCB 
Ox4FCC 
Ox4FCC 
Ox4FCD 
Ox4FCD 
Ox4FCE 
Ox4FCE 
Ox4FCF 
Ox4FCF 
Ox4FDO 
0x4FDO 
Ox4FD1 
Ox4FD1 
Ox4FD2 
Ox4FD2 


PMERR_CANNOT_DEL_QP_REF 
MERR_CANNOT_DEL_QP_REF 
PMERR_CANNOT_DEL_QNAME_REF 
MERR_CANNOT_DEL_QNAME_REF 
PMERR_CANNOT_DEL_PRINTER_DD_REF 
MERR_CANNOT_DEL PRINTER DD REF 
PMERR_CANNOT_DEL_PRN_NAME_REF 
MERR_CANNOT_DEL_PRN_NAME_REF 
PMERR_CANNOT_DEL_PRN_ADDR_REF 
MERR_CANNOT_DEL_PRN_ADDR_REF 
PMERR_SPOOLER_QP_NOT_DEFINED 
MERR_SPOOLER_QP_NOT_DEFINED 
PMERR_PRN_NAME_NOT_DEFINED 
MERR_PRN_NAME_NOT_DEFINED 
PMERR_PRN_ADDR_NOT_DEFINED 
MERR_PRN_ADDR_NOT_DEFINED 
PMERR_PRINTER_DD NOT DEFINED 
MERR_PRINTER_DD_NOT_ DEFINED 
PMERR_PRINTER_QUEUE_NOT DEFINED 
MERR_PRINTER_QUEUE_NOT_DEFINED 
PMERR_PRN_ADDR_IN_USE 
MERR_PRN_ADDR_IN_USE 
PMERR_SPL_TOO MANY_OPEN FILES 
MERR_SPL_TOO_MANY_OPEN FILES 
PMERR_SPL_CP_NOT_REQD 
MERR_SPL_CP_NOT_REQD 
PMERR_UNABLE_TO_CLOSE_DEVICE 
MERR_UNABLE_TO_CLOSE_DEVICE 
PMERR_SPLMSGBOX_INFO_CAPTION 
MERR_SPLMSGBOX_INFO_CAPTION 
PMERR_SPLMSGBOX_WARNING_CAPTION 
MERR_SPLMSGBOX_WARNING_CAPTION 
PMERR_SPLMSGBOX_ERROR_CAPTION 
MERR_SPLMSGBOX_ERROR_CAPTION 
PMERR_SPLMSGBOX_SEVERE_CAPTION 
MERR_SPLMSGBOX_SEVERE_CAPTION 
PMERR_SPLMSGBOX_JOB_DETAILS 
MERR_SPLMSGBOX_JOB_DETAILS 
PMERR_SPLMSGBOX_ERROR_ACTION 
MERR_SPLMSGBOX_ERROR_ACTION 
PMERR_SPLMSGBOX_SEVERE_ACTION 
MERR_SPLMSGBOX_SEVERE_ACTION 
PMERR_SPLMSGBOX_BIT_O TEXT 
MERR_SPLMSGBOX_BIT_0_TEXT 
PMERR_SPLMSGBOX_BIT_1_ TEXT 
MERR_SPLMSGBOX_BIT_1_TEXT 
PMERR_SPLMSGBOX_BIT_2 TEXT 
MERR_SPLMSGBOX_BIT_2 TEXT 
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Ox4FD3 
0x4FD3 
Ox4FD4 
Ox4FD4 
Ox4FD5 
Ox4FD5 
Ox4FD6 
Ox4FD6 
Ox4FD7 
Ox4FD7 
Ox4FD8 
Ox4FD9 
0x5001 
0x5001 
0x5002 
0x5002 
0x5003 
0x5003 
0x5004 
0x5004 
0x5005 
0x5005 
0x5006 
0x5006 
0x5007 
0x5007 
0x5008 
0x5008 
0x5009 
0x5009 
0x5010 
0x5010 


PMERR_SPLMSGBOX_BIT_3_ TEXT 
MERR_SPLMSGBOX_BIT_3_ TEXT 
PMERR_SPLMSGBOX_BIT_4_ TEXT 
MERR_SPLMSGBOX_BIT_4_ TEXT 
PMERR_SPLMSGBOX_BIT_5_TEXT 
MERR_SPLMSGBOX_BIT_5 TEXT 
PMERR_SPLMSGBOX_BIT_15_ TEXT 
MERR_SPLMSGBOX_BIT_15_TEXT 
PMERR_SPL_NOPATHBUFFER 
MERR_SPL_NOPATHBUFFER 
MERR_SPL_ALREADY_INITIALISED 
MERR_SPL_ERROR 
PMERR_INV_TYPE 
MERR_INV_TYPE 
PMERR_INV_CONV 
MERR_INV_CONV 
PMERR_INV_SEGLEN 
MERR_INV_SEGLEN 
PMERR_DUP_SEGNAME 
MERR_DUP_SEGNAME 
PMERR_INV_XFORM 
MERR_INV_XFORM 
PMERR_INV_VIEWLIM 
MERR_INV_VIEWLIM 
PMERR_INV_3DCOORD 
MERR_INV_3DCOORD 
PMERR_SMB_OVFLOW 
MERR_SMB_OVFLOW 
PMERR_SEG_OVFLOW 
MERR_SEG_OVFLOW 
PMERR_PIC_DUP_FILENAME 
MERR_PIC_DUP_FILENAME 


SPLERR_BASE+0FA1 
SPLERR_BASE+0FA2 
SPLERR_BASE+0FA3 
SPLERR_BASE+0FA4 
SPLERR_BASE+0FA5 
SPLERR_BASE+0FA6 
SPLERR_BASE+0FA7 
SPLERR_BASE+0FA8 
SPLERR_BASE+0FA9 
SPLERR_BASE+0FAA 
SPLERR_BASE+0FAB 
SPLERR_BASE+0FAC 
SPLERR_BASE+0FAD 
SPLERR_BASE+0FAE 
SPLERR_BASE+0FAF 
SPLERR_BASE+0FB0 


PMERR_SPL_ERROR_1 
PMERR_SPL_ERROR 2 
PMERR_SPL_ERROR 3 
PMERR_SPL_ERROR 4 
PMERR_SPL_ERROR_5 
PMERR_SPL_ERROR 6 - 
PMERR_SPL_ERROR 7 
PMERR_SPL_ERROR_8 
PMERR_SPL_ERROR 9 


PMERR_SPL_ERROR_10 


PMERR_SPL_ERROR_11 


PMERR SPL_ERROR_ 12 
PMERR_SPL_ERROR_13 


PMERR_SPL_ERROR_14 
PMERR_SPL_ERROR_15 
PMERR_SPL_ERROR_16 
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SPLERR_BASE+0FB1 
SPLERR_BASE+0FB2 
SPLERR_BASE+0FB3 
SPLERR_BASE+0FB4 
SPLERR_BASE+0FB5 
SPLERR_BASE+0FB6 
SPLERR_BASE+0FB7 
SPLERR_BASE+0FB8 
SPLERR_BASE+0FB9 
SPLERR_BASE+0FBA 
SPLERR_BASE+0FBB 
SPLERR_BASE+0FBC 
SPLERR_BASE+0FBD 
SPLERR_BASE+0FBE 
SPLERR_BASE+0FBF 
SPLERR_BASE+0FCO 
SPLERR_BASE+0FC1 
SPLERR_BASE+0FC2 
SPLERR_BASE+0FC3 
SPLERR_BASE+0FC4 
SPLERR_BASE+0FC5 
SPLERR_BASE+0FC6 
SPLERR_BASE+0FC7 
SPLERR_BASE+0FC8 
SPLERR_BASE+0FFF 
SPLERR_BASE+0FFD 


PMERR_SPL_ERROR_17 
PMERR_SPL_ERROR_18 
PMERR_SPL_ERROR_19 
PMERR_SPL_ERROR_20 
PMERR_SPL_ERROR_21 
PMERR_SPL_ERROR_22 
PMERR_SPL_ERROR_23 
PMERR_SPL_ERROR_24 
PMERR_SPL_ERROR_25 
PMERR_SPL_ERROR_26 
PMERR_SPL_ERROR_27 
PMERR_SPL_ERROR_28 
PMERR_SPL_ERROR_29 
PMERR_SPL_ERROR_30 
PMERR_SPL_ERROR_31 
PMERR_SPL_ERROR_32 
PMERR_SPL_ERROR_33 
PMERR_SPL_ERROR_34 
PMERR_SPL_ERROR_35 
PMERR_SPL_ERROR_36 
PMERR_SPL_ERROR_37 
PMERR_SPL_ERROR_38 
PMERR_SPL_ERROR_39 
PMERR_SPL_ERROR_40 
PMERR_SPL_ERROR 


PMERR_SPL_ALREADY_INITIALISED 
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Appendix C. Error Explanations 


This appendix gives an explanation for each PM error. The errors are listed in alphabetic 
order. The number associated with each error is given in Appendix B, “Error Codes” on 


page B-1. 
Error Constant 
HMERR_ALLOCATE_SEGMENT 


HMERR_CLOSE_LIB_FILE 
HMERR_CONTENT_NOT_FOUND 
HMERR_DATABASE_NOT_OPEN 
HMERR_DDF_ALIGN_TYPE 
HMERR_DDF_BACKCOLOR 
HMERR_DDF_EXCEED_MAX_INC 


HMERR_DDF_EXCEED_MAX_LENGTH 


HMERR_DDF_FONTSTYLE 
HMERR_DDF_FORECOLOR 
HMERR_DDF_FORMAT_TYPE 
HMERR_DDF_HINSTANCE 
HMERR_DDF_INVALID_DDF 
HMERR_DDF_INVALID_FONT 

_ HMERR_DDF_INVALID_PARM 


HMERR_DDF_LIST_BREAKTYPE 
HMERR_DDF_LIST_SPACING 
HMERR_DDF_LIST_UNCLOSED 
HMERR_DDF_LIST_UNINITIALIZED 


HMERR_DDF_MEMORY 
HMERR_DDF_REFTYPE 
HMERR_DDF_SEVERE 


HMERR_FREE_MEMORY 


© Copyright IBM Corp. 1994 


Explanation 


Unable to allocate a segment of memory 
for memory allocation requests from the 
Help Manager. 


The library file cannot be closed. 

The library file does not have any content. 
Unable to read the unopened database. 
The alignment type is not valid. 

The background color is not valid. 


The value specified to increment DDF 
memory is too large. 


The amount of data is too large for the 
DDF buffer. 


The font style is not valid. 

The foreground color is not valid. 
The format type specified is invalid. 
The DDF instance. is invalid. 

The DDF handle is invalid. 

The font value specified is invalid. 


One of the DDF parameters specified is 
invalid. 


The value of BreakType is not valid. 
The value for Spacing is not valid. 
An attempt was made to nesi a list. 


No definition list has been initialized by 
DdfBeginList. 


Not enough memory is available. 
The reference type is not valid. 


Internal error detected by the Help 
Manager. 


Unable to free allocated memory. 


C-2 


HMERR_HELP_INST_CALLED _ INVALID 


HMERR_HELP_INSTANCE_UNDEFINE 


HMERR_HELPITEM_NOT_FOUND 
HMERR_HELPSUBITEM_NOT_FOUND 


HMERR_HELPTABLE_UNDEFINE 


HMERR_INDEX_NOT_FOUND 
HMERR_INVALID_ASSOC_APP_WND 


HMERR_INVALID_ASSOC_HELP_INST 
HMERR_INVALID_DESTROY_HELP_INST 
HMERR_INVALID_HELP_INSTANCE_HDL 


HMERR_INVALID_HELPSUBITEM_ SIZE 
HMERR_INVALID_LIB_FILE 
HMERR_INVALID_QUERY_APP_WND 


HMERR_LOAD_DLL 
HMERR_NO_FRAME_WND_IN_CHAIN 


HMERR_NO_HELP_INST_IN_CHAIN 


HMERR_NO_MEMORY 
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The handle of the instance specified on a 
call to the Help Manager does not have the 
class name of a Help Manager instance. 


The help instance handle specified is 
invalid. 


Context-sensitive help was requested but 
the ID of the main help item specified was 
not found in the help table. 


Context-sensitive help was requested but 
the ID of the help item specified was not 
found in the help subtable. 


The application did not provide a help table 
for context-sensitive help. 


The index is not in the library file. 


The application window handle specified on 
the WinAssociateHelpInstance function is 
not a valid window handle. 


The help instance handle specified on the 
WinAssociateHelpInstance function is not a 
valid window handle. 


The window handle specified as the help 
instance to destroy is not of the help 
instance class. 


The handle specified to be a help instance 
does not have the class name of a Help 
Manager instance. 


The help subtable item size is less than 2. 
Improper library file provided. 


The application window specified on a 
WinQueryHelpInstance function is not a 
valid window handle. | 


Unable to load resource data link library. 


There is no frame window in the window 
chain from which to find or set the 
associated help instance. 


The parent or owner chain of the 
application window specified does not have 
an associated help instance. 


Unable to allocate the requested amount of 
memory. 


HMERR_OPEN_LIB_FILE 
HMERR_PANEL_NOT_FOUND 
HMERR_READ LIB FILE 
PMERR_ACCESS_ DENIED 


PMERR_ALREADY_IN_AREA 


PMERR_ALREADY_IN_ELEMENT 


PMERR_ALREADY_IN_PATH 


PMERR_ALREADY_IN_SEG 


PMERR_APPL_STRUCTURE_TOO_SMALL 


PMERR_AREA_INCOMPLETE 


PMERR_ARRAY_TOO_LARGE 


PMERR_ARRAY_TOO_SMALL 
PMERR_ATOM_NAME_NOT_FOUND 


PMERR_BASE_ERROR 


PMERR_BITMAP_IN_USE 


The library file cannot be opened. 
Unable to find the requested help panel. 
The library file cannot be read. 


The memory block was not allocated 
properly. 
An attempt was made to begin a new area 


while an existing area bracket was already 
open. 


An attempt was made to begin a new 
element while an existing element bracket 
was already open. 


An attempt was made to begin a new path 
while an existing path bracket was already 
open. 


An attempt was made to open a new 
segment while an existing segment bracket 
was already open. 


The application buffer length is less than 
the total length required for the (application) — 
component types. 


One of the following has occurred: 


e A segment has been opened, closed, 
or drawn. 

e GpiAssociate was issued while an area 
bracket was open. 

¢ A drawn segment has opened an area 
bracket and ended without closing it. 


More than 4 bytes was attempted to be 
inserted or extracted. 


The array specified was too small. 


The specified atom name is not in the atom 
table. ; 


An OS/2 base error has occurred. The 
base error code can be accessed using the 
OffBinaryData field of the ERRINFO 
structure returned by WinGetErrorInfo. 


An attempt was made either to set a bit 
map into a device context using 
GpiSetBitmap while it was already selected 
into an existing device context, or to tag a 
bit map with a local pattern set identifier 
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PMERR_BITMAP_IS_ SELECTED 
PMERR_BITMAP_NOT_FOUND 


PMERR_BITMAP_NOT_SELECTED 


PMERR_BOUNDS_OVERFLOW 


PMERR_BUFFER_TOO_SMALL 


PMERR_C_LENGTH_TOO SMALL 


PMERR_CALLED_SEG_IS_ CHAINED 
PMERR_CALLED_SEG_IS_CURRENT 
PMERR_CALLED_SEG_NOT_FOUND 


PMERR_CAN_NOT_CALL_SPOOLER 


PMERR_CANNOT_DEL_PRINTER_DD_REF 


PMERR_CANNOT_DEL_PRN_ADDR_REF 
PMERR_CANNOT_DEL_PRN_NAME_REF 
PMERR_CANNOT_DEL_QNAME_REF 
PMERR_CANNOT_DEL_QP_REF 


PMERR_CANNOT_STOP 
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(setid) using GpiSetBitmapld while it was 
already tagged with an existing setid. 


An attempt was made to delete a bit map 
while it was selected into a device context. 


A attempt was made to perform a bit-map 
operation on a bit map that did not exist. 


A attempt was made to perform an 
operation on presentation space associated 
with a memory device context that had no 
selected bit map. 


An internal overflow error occurred during 
boundary data accumulation. This can 
occur if coordinates or matrix 
transformation elements (or both) are 
invalid or too large. 


The supplied buffer was not large enough 
for the data to be returned. 


The maximum length of the C structure is 
less than the total length required for the 
(C) component types. 


An attempt was made to call a segment 
that has a chained attribute set. 


An attempt was made to call a segment 
that is currently open. 


An attempt was made to call a segment 
that did not exist. 


An error occurred attempting to cali the 
spooler validation routine. This error is not 
raised if the spooler is not installed. 


Presentation Manager device driver 
deletion not possible due to a reference. 


Printer port deletion not possible due to a 
reference. 


Printer deletion not possible due to a 
reference. 


Spooler queue deletion not possible due to 
a reference. 


Spooler queue processor deletion not 
possible due to a reference. 


The session cannot be stopped. 


PMERR_COL_TABLE_NOT_REALIZABLE 


PMERR_COL_TABLE_NOT_REALIZED 


PMERR_COORDINATE_OVERFLOW 


PMERR_DATA_TOO LONG 


PMERR_DATATYPE_ENTRY_BAD_INDEX 
PMERR_DATATYPE_ENTRY_CTL_BAD 


PMERR_DATATYPE_ENTRY._CTL_MiSS 
PMERR_DATATYPE_ENTRY_NOT_NUM 


PMERR_DATATYPE_ENTRY_NOT_OFF 


PMERR_DATATYPE_INVALID 
PMERR_DATATYPE_NOT_UNIQUE 


PMERR_DATATYPE_TOO_LONG 
PMERR_DATATYPE_TOO_SMALL 
PMERR_DC_IS_ASSOCIATED 


PMERR_DEL_NOT_ALLOWED 
PMERR_DESC_STRING_TRUNCATED 


PMERR_DEV_FUNC_NOT_INSTALLED 


An attempt was made to realize a color 
table that is not realizable. 


An attempt was made to realize a color 
table on a device driver that does not 
support this function. 


An internal coordinate overflow error 
occurred. This can occur if coordinates or 
matrix transformation elements (or both) 
are invalid or too large. 


An attempt was made to transfer more than 
the maximum permitted amount of data 
(64512 bytes) using GpiPutData, 
GpiGetData, or GpiElement. 


An invalid datatype entry index was 
specified. 


An invalid datatype entry control was 
specified. 


The datatype entry control was missing. 


The datatype entry specified was not 
numerical. 


The datatype entry specified was not an 
offset. 


An invalid datatype was specified. 


An attempt to register a datatype failed 
because it is not unique. 


The datatype specified was too long. 
The datatype specified was too small. 


An attempt was made to associate a 
presentation space with a device context 
that was already associated or to destroy a 
device context that was associated. 


Deletion not possible. 


An attempt was made to supply a 
description string with GpiBeginElement 
that was greater then the permitted 
maximum length (251 characters). The 
string was truncated. 


The function requested is not supported by 
the presentation driver. 
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PMERR_DEVICE_DRIVER_ERROR_1 
PMERR_DEVICE_DRIVER_ERROR_10 
PMERR_DEVICE_DRIVER_ERROR_2 
PMERR_DEVICE_DRIVER_ERROR_3 
PMERR_DEVICE_DRIVER_ERROR_4 
PMERR_DEVICE_DRIVER_ERROR_5 
PMERR_DEVICE_DRIVER_ERROR_6 
PMERR_DEVICE_DRIVER_ERROR _7 
PMERR_DEVICE_DRIVER_ERROR_8 
PMERR_DEVICE_DRIVER_ERROR_9 


PMERR_DOS_ERROR 
PMERR_DOSOPEN_FAILURE 


PMERR_DOSREAD_FAILURE 


PMERR_DRIVER_NOT_FOUND 


PMERR_DUP_SEG 


PMERR_DUP_SEGNAME 
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Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


Miscellaneous error available for use by 
user written device drivers. 


A DOS call returned an error. 


A DosOpen call made during 
GpiLoadMetaFile or GpiSaveMetaFile gave 
a good return code but the file was not 
opened successfully. 


A DosRead call made during 
GpiLoadMetaFile gave a good return code. 
However, it failed to read any more bytes 
although the file length indicated that there 
were more to be read. 


The device driver specified with 
DevPostDeviceModes was not found. 


During GpiPlayMetaFile, while the actual 
drawing mode was draw-and-retain or 
retain, a metafile segment to be stored in 
the presentation space was found to have 
the same segment identifier as an existing 
segment. 


A called segment has a name that has 
already been used by another called 
segment in the input PIF. 


PMERR_DUPLICATE_TITLE 


PMERR_DYNAMIC_SEG_SEQ_ERROR 


PMERR_DYNAMIC_SEG_ZERO_INV 
PMERR_ENDDOC_NOT_ISSUED 


PMERR_ESC_CODE_NOT_SUPPORTED 


PMERR_EXCEEDS_MAX_SEG_LENGTH 


PMERR_FONT_AND_MODE_MISMATCH 


PMERR_FONT_FILE_NOT_LOADED 
PMERR_FONT_NOT_LOADED 


PMERR_FUNCTION_NOT_SUPPORTED 
PMERR_GREATER_THAN_64K 


-PMERR_HBITMAP_BUSY 


The program title specified in the 
PIBSTRUCT already exists within the same 
group. 

During removal of dynamic segments while 
processing GpiDrawChain, GpiDrawFrom, 
or GpiDrawSegment, the internal state 
indicated that dynamic segment data was 
still visible after all chained dynamic 
segments had been processed. This can 
occur if segments drawn dynamically 
(including called segments) are modified or 
removed from the chain while visible. 


An attempt was been made to open a 
dynamic segment with a segment identifier 
of zero. 


A request to close the spooled output 
without first issuing a an ENDDOC was 
attempted. 


The code specified with DevEscape is not 
supported by the target device driver. 


During metafile creation or generation of 
retained graphics the system has exceeded 
maximum segment size. 


An attempt was made to draw characters 
with a character mode and character set 
that are incompatible. For example, the 
character specifies an image/raster font 
when the mode calls for a vector/outline 
font. 


An attempt was made to unload a font file 
that was not loaded. 


An attempt was made to create a font that 
was not loaded. 


The function is not supported. 


A data item or array dimension is greater 
than 65 535. 


An internal bit map busy error was 
detected. The bit map was locked by one 
thread during an attempt to access it from 
another thread. 
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PMERR_HDC_BUSY 


PMERR_HEAP_MAX_SIZE_REACHED 
PMERR_HEAP_OUT_OF_MEMORY 


- PMERR_HFONT_IS_ SELECTED 


PMERR_HRGN_BUSY 


PMERR_HUGE_FONTS_NOT SUPPORTED 


PMERR_ID_HAS_NO_BITMAP 


PMERR_IMAGE_INCOMPLETE 


PMERR_INCOMPATIBLE_BITMAP 


PMERR_INCOMPATIBLE_METAFILE 


PMERR_INCORRECT_DATATYPE 


PMERR_INCORRECT_DC_TYPE 
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‘An internal device context busy error was 


detected. The device context was locked 
by one thread during an attempt to access 
it from another thread. 


The heap has reached its maximum size 
(64KB), and cannot be increased. 


An attempt to increase the size of the heap 
failed. 


An attempt has been made to either 
change the owner of a font, or delete when 
it is currently selected. 


An internal region busy error was detected. 
The region was locked by one thread 


during an attempt to access it from another 


thread. 


An attempt was made using 
GpiSetCharSet, GpiSetPatternSet, 
GpiSetMarkerSet, or GpiSetAttrs to select a 
font that is larger than the maximum size 
(64Kb) supported by the target device 
driver. 


No bit map was tagged with the setid 
specified on a GpiQueryBitmapHandle 
function. 


A drawn segment has opened an image 
bracket and ended without closing it. 


An attempt was made to select a bit map or 
perform a BitBIt operation on a device 
context that was incompatible with the 
format of the bit map. 


An attempt was made to associate a 
presentation space and a metafile device 
context with incompatible page units, size 
or coordinate format; or to play a metafile 
using the RES_RESET option (to reset the 
presentation space) to a presentation space 
that is itself associated with a metafile 
device context. 


A data type is specified which is incorrect 
for this function. 


An attempt was made to perform a bit-map 
operation on a presentation space 
associated with a device context of a type 


PMERR_INCORRECT_HSTRUCT 


PMERR_INI_FILE_IS SYS OR_USER 
PMERR_INSUFF_SPACE_TO_ADD 
PMERR_INSUFFICIENT_DISK_SPACE 
PMERR_INSUFFICIENT_MEMORY 
PMERR_INV_ANGLE _PARM 
PMERR_INV_ARC_CONTROL 
PMERR_INV_AREA_CONTROL 
PMERR_INV_ATTR_MODE 


PMERR_INV_BACKGROUND_COL_ATTR 


PMERR_INV_BACKGROUND_MIX_ATTR 


PMERR_INV_BITBLT_MIX 
PMERR_INV_BITBLT_STYLE 


PMERR_INV_BITMAP_DATA 


that is unable to support bit-map 
operations. 


A structure handle is non-NULL, and is 
invalid for one of the following reasons: 


e It is not the handle of a data structure. 

e {tis the handle of an ERRINFO 
structure, which should not be used in 
this call. 

e A handle block returned by the 
bindings to the application has been 
used for an in-line structure handle. 


User or system initialization file cannot be 
closed. 


The initialization file could not be extended 
to add the required program or group. 


The operation terminated through 
insufficient disk space. 


The operation terminated through 
insufficient memory. 


An invalid angle parameter was specified 
with GpiPartialArc. 


An invalid control parameter was specified 
with GpiFullArc. 


An invalid options parameter was specified 
with GpiBeginArea. 


An invalid mode parameter was specified 
with GpiSetAttrMode. 


An invalid background color attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid background mix attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid /Rop was specified with a 
GpiBitBlt or GpiWCBitBIt function. 


An invalid options parameter was specified 
with a GpiBitBlt or GpiWCBIitBlt function. 


In processing a bit map, the end of the data 
was unexpectedly encountered. 
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PMERR_INV_BITMAP_DIMENSION 
PMERR_INV_BOX_CONTROL 
PMERR_INV_BOX_ROUNDING_PARM 
PMERR_INV_CHAR_ALIGN_ATTR 


PMERR_INV_CHAR_ANGLE_ATTR 


PMERR_INV_CHAR_DIRECTION_ATTR 
PMERR_INV_CHAR_MODE_ATTR 


PMERR_INV_CHAR_POS_OPTIONS 


PMERR_INV_CHAR_SET_ATTR 
PMERR_INV_CHAR_SHEAR_ATTR 


PMERR_INV_CLIP_PATH_OPTIONS 
PMERR_INV_CODEPAGE 


PMERR_INV_COLOR_ATTR 


PMERR_INV_COLOR_DATA 


PMERR_INV_COLOR_FORMAT 
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An invalid dimension was specified with a 
load bit-map function. 


An invalid control parameter was specified 
with GpiBox. 


An invalid corner rounding control 
parameter was specified with GpiBox. 


The text alignment attribute specified in 
GpiSetTextAlignment is not valid. 


The default character angle attribute value 
was explicitly specified with GpiSetAttrs 
instead of using the defaults mask. 


An invalid character direction attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid character mode attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid options parameter was specified 
with GpiCharStringPos or 
GpiCharStringPosAt. 


An invalid character setid attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid character shear attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid options parameter was specified 
with GpiSetClipPath. 


An invalid code-page parameter was 
specified with GpiSetCp. 


An invalid color attribute value was 
specified or the default value was explicitly 
specified with GpiSetAttrs instead of using 
the defaults mask. 


Invalid color table definition data was 
specified with GpiCreateLogColorTable. 


An invalid format parameter was specified 
with GpiCreateLogColorTable. 


PMERR_INV_COLOR_INDEX 


PMERR_INV_COLOR_OPTIONS 


PMERR_INV_COLOR_START_INDEX 


PMERR_INV_CONV 
PMERR_INV_COORD_OFFSET 
PMERR_INV_COORD_SPACE 


PMERR_INV_COORDINATE 
PMERR_INV_CORRELATE_DEPTH 


PMERR_INV_CORRELATE_TYPE 


PMERR_INV_CURSOR_BITMAP 
PMERR_INV_DC_DATA 


PMERR_INV_DC_TYPE 


PMERR_INV_DEV_MODES_OPTIONS 
PMERR_INV_DEVICE_NAME 
PMERR_INV_DRAW_BORDER_OPTION 


PMERR_INV_DRAW_CONTROL 


PMERR_INV_DRAW_VALUE 


An invalid color index parameter was 
specified with GpiQueryRGBColor. 


An invalid options parameter was specified 
with a logical color table or color query 
function. 


An invalid starting index parameter was 
specified with a logical color table or color 
query function. 


Invalid conversion-type parameter. 


An invalid coordinate offset value was 
specified. 


An invalid source or target coordinate 
space parameter was specified with 
GpiConvert. 


An invalid coordinate value was specified. 


An invalid maxdepth parameter was 
specified with GpiCorrelateSegment, 
GpiCorrelateFrom, or GpiCorrelateChain. 


An invalid type parameter was specified 
with GpiCorrelateSegment, 
GpiCorrelateFrom, or GpiCorrelateChain. 


An invalid pointer was referenced with 
WinSetPointer. 


An invalid data parameter was specified 
with DevOpenDC. 


An invalid type parameter was specified 
with DevOpenDC, or a function was issued 
that is invalid for a 
OD_METAFILE_NOQUERY device context. 


An invalid options parameter was specified 
with DevPostDeviceModes. 


An invalid devicename parameter was 
specified with DevPostDeviceModes. 


An invalid option parameter was specified 
with WinDrawBorder. 


An invalid control parameter was specified 
with GpiSetDrawControl or 


-GpiQueryDrawControl. 


An invalid value parameter was specified 
with GpiSetDrawControl. 
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PMERR_INV_DRAWING_MODE 
PMERR_INV_DRIVER_DATA 
PMERR_INV_DRIVER_NAME 
PMERR_INV_EDIT_MODE 
PMERR_INV_ELEMENT_OFFSET 


PMERR_INV_ELEMENT_POINTER 


PMERR_INV_END_PATH_OPTIONS 
PMERR_INV_ESC_CODE 
PMERR_INV_ESCAPE_DATA 
PMERR_INV_FACENAME 


PMERR_INV_FACENAMEDESC 
PMERR_INV_FILL_PATH_OPTIONS 


PMERR_INV_FIRST_CHAR 


PMERR_INV_FLOOD_FILL_OPTIONS 
PMERR_INV_FONT_ATTRS 


PMERR_INV_FONT_FILE_DATA 


PMERR_INV_FOR_THIS_DC_TYPE 


PMERR_INV_FORMS_CODE 
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An invalid mode parameter was specified 
with GpiSetDrawControl not 
draw-and-retain or draw. 


Invalid driver data was specified. 


A driver name was specified which has not 
been installed. 


An invalid mode parameter was specified 
with GpiSetEditMode. 


An invalid off (offset) parameter was 
specified with GpiQueryElement. 


An attempt was made to issue GpiPutData 
with the element pointer not pointing at the 
last element. 


An attempt to create or delete a path out of 
context of the path bracket was made. 


An invalid escape code was used in a call 
to DevEscape. 


An invalid data parameter was specified 
with DevEscape. 


An invalid font family name was passed to 
GpiQueryFaceString. 


The font facename description is invalid. 


An invalid options parameter was specified 
with GpiFillPath. 


An invalid firstchar parameter was specified 
with GpiQueryWidthTable. 


Invalid flood fill parameters were specified. 


An invalid attrs parameter was specified 
with GpiCreateLogFont. 


The font file specified with GpiLoadFonts, 
GpiLoadPublicFonts, 
GpiQueryFontFileDescriptions, or 
GpiQueryFullFontFileDescs contains invalid 
data. 


An attempt has been made to issue 
GpiRemoveDynamics or GpiDrawDynamics 
to a presentation space associated with a 
metafile device context. 


An invalid forms code parameter was 
specified with DevQueryHardcopyCaps. 


PMERR_INV_GEOM_LINE_WIDTH_ATTR 
PMERR_INV_GETDATA_CONTROL 
PMERR_INV_GRAPHICS FIELD 
PMERR_INV_HBITMAP 


PMERR_INV_HDC 


PMERR_INV_HFONT 
PMERR_INV_HMF 
PMERR_INV_HPAL 


PMERR_INV_HPS 


PMERR_INV_HRGN 
PMERR_INV_ID 


PMERR_INV_IMAGE_DATA_LENGTH 


PMERR_INV_IMAGE_DIMENSION 
PMERR_INV_IMAGE_FORMAT 


PMERR_INV_IN_ AREA 


PMERR_INV_IN_CURRENT_EDIT_MODE 
PMERR_INV_IN_ELEMENT 
PMERR_INV_IN_IMAGE 


PMERR_INV_IN_PATH 


An invalid geometric line width attribute 
value was specified. 


An invalid format parameter was specified 
with GpiGetData. 


An invalid field parameter was specified 
with GpiSetGraphicsField. 


An invalid bit-map handle was specified. 


An invalid device-context handle or (micro 
presentation space) presentation-space 
handle was specified. 


An invalid font handle was specified. 

An invalid metafile handle was specified. 
An invalid color palette handle was 
specified. 

An invalid presentation-space handle was 
specified. 

An invalid region handle was specified. 


An invalid [PSid parameter was specified 
with GpiRestorePS. 


An invalid /Length parameter was specified 
with Gpilmage. There is a mismatch 
between the image size and the data 
length. 


An invalid psiziimageSize parameter was 
specified with Gpilmage. 


An invalid /Format parameter was specified 
with Gpilmage. 


An attempt was made to issue a function 
invalid inside an area bracket. This can be 
detected while the actual drawing mode is 
draw or draw-and-retain or during 
segment drawing or correlation functions. 


An attempt was made to issue a function 
invalid inside the current editing mode. 


An attempt was made to issue a function 
invalid inside an element bracket. 


An attempt was made to issue a function 
invalid inside an element bracket. 


An attempt was made to issue a function 
invalid inside a path bracket. 
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PMERR_INV_IN_RETAIN_MODE 


PMERR_INV_IN_SEG 


PMERR_INV_IN_VECTOR_SYMBOL 


PMERR_INV_INFO_TABLE 
PMERR_INV_LENGTH_OR COUNT 
PMERR_INV_LINE_END_ATTR 
PMERR_INV_LINE_JOIN ATTR 


PMERR_INV_LINE_TYPE_ATTR 
PMERR_INV_LINE_WIDTH_ATTR 


PMERR_INV_LOGICAL_ADDRESS 
PMERR_INV_MARKER_BOX_ATTR 


PMERR_INV_MARKER_SET_ATTR 
PMERR_INV_MARKER_SYMBOL_ATTR 


PMERR_INV_MATRIX_ELEMENT 


PMERR_INV_MAX_HITS 
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An attempt was made to issue a function 
(for example, query) that is invalid when the 
actual drawing mode is not draw or 
draw-and-retain. 


An attempt was made to issue a function 
invalid inside a segment bracket. 


An invalid order was detected inside a 
vector symbol definition while drawing a 
vector (outline) font. 


An invalid bit-map info table was specified 
with a bit-map operation. 


An invalid length or count parameter was 
specified. 


An invalid line end attribute value was 
specified. 


An invalid line join attribute value was 
specified. 


An invalid line type attribute value was 
specified or the default value was explicitly 
specified with GpiSetAttrs instead of using 
the defaults mask. 


An invalid line width attribute value was 
specified or the default value was explicitly 
specified with GpiSetAttrs instead of using 
the defaults mask. 


An invalid device logical address was 
specified. 


An invalid marker box attribute value was 
specified. 


An invalid marker set attribute value was 
specified or the default value was explicitly 
specified with GpiSetAttrs instead of using 
the defaults mask. 


An invalid marker symbol attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid transformation matrix element 
was specified. 


An invalid maxhits parameter was specified 
with GpiCorrelateSegment, 
GpiCorrelateFrom, or GpiCorrelateChain. 


PMERR_INV_METAFILE 


PMERR_INV_METAFILE_LENGTH 
PMERR_INV_METAFILE_OFFSET 
PMERR_INV_MICROPS_DRAW_CONTROL 
PMERR_INV_MICROPS_FUNCTION 
PMERR_INV_MICROPS_ORDER 


PMERR_INV_MIX_ATTR 
PMERR_INV_MODE_FOR_OPEN_DYN 


PMERR_INV_MODE_FOR_REOPEN_SEG 


PMERR_INV_MODIFY_PATH_MODE 
PMERR_INV_MULTIPLIER 
PMERR_INV_NESTED_FIGURES 


PMERR_INV_OR_INCOMPAT_OPTIONS 


PMERR_INV_ORDER_LENGTH 


PMERR_INV_ORDERING_PARM 


An invalid metafile was specified with 
GpiPlayMetaFile. 


An invalid length parameter was specified 
with GpiSetMetaFileBits or 
GpiQueryMetaFileBits. 


An invalid length parameter was specified 
with GpiSetMetaFileBits or 
GpiQueryMetaFileBits. 


A draw control parameter was specified 
with GpiSetDrawControl that is invalid in a 
micro presentation space. 


An attempt was made to issue a function 
that is invalid in a micro presentation 
space. 


An attempt was made to play a metafile 
containing orders that are invalid in a micro 
presentation space. 


An invalid mix attribute value was specified 
or the default value was explicitly specified 
with GpiSetAttrs instead of using the 
defaults mask. 


An attempt was made to open a segment 
with the ATTR_DYNAMIC segment set, 
while the drawing mode was set to 
DM_DRAW or DM_DRAWANDRETAIN. 


An attempt was made to reopen an existing 
segment while the drawing mode was set 
to DM_DRAW or DM_DRAWANDRETAIN. 


An invalid mode parameter was specified 
with GpiModifyPath. 


An invalid multiplier parameter was 
specified with GpiPartialArc or GpiFullArc. 


Nested figures have been detected within a 
path definition. 


An invalid or incompatible (with micro 
presentation space) options parameter was 
specified with GpiCreatePS or GpiSetPS. 


An invalid order length was detected during 
GpiPutData or segment drawing. 


An invalid order parameter was specified 
with GpiSetSegmentPriority. 
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PMERR_INV_OUTSIDE_DRAW_MODE 


PMERR_INV_PAGE_VIEWPORT 
PMERR_INV_PATH_ID 


PMERR_INV_PATTERN_ATTR 


PMERR_INV_PATTERN_REF_PT_ATTR 


PMERR_INV_PATTERN_SET_ATTR 


PMERR_INV_PATTERN_SET_FONT 
PMERR_INV_PICK_APERTURE_OPTION 
PMERR_INV_PICK_APERTURE_POSN 
PMERR_INV_PICK APERTURE. SIZE 
PMERR_INV_PLAY_METAFILE_OPTION 
PMERR_INV_PRIMITIVE_TYPE 
PMERR_INV_PS_SIZE 
PMERR_INV_PUTDATA_FORMAT 
PMERR_INV_QUERY_ELEMENT_NO 


PMERR_INV_RECT 
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An attempt was made to issue a 
GpiSavePS or GpiRestorePS function, or 
an output only function (for example, 
GpiPaintRegion) from GpiPlayMetaFile 
without the drawing mode set to 
DM_DRAW. ; 


An invalid viewport parameter was specified 
with GpiSetPageViewport. 


An invalid path identifier parameter was 
specified. 


An invalid pattern symbol attribute value 
was specified or the default value was 
explicitly specified with GpiSetAttrs instead 
of using the defaults mask. 


An invalid refpoint attribute value was 
specified. 


An invalid pattern set attribute value was 
specified or the default value was explicitly 
specified with GpiSetAttrs instead of using 
the defaults mask. 


An attempt was made to use an unsuitable 
font as a pattern set. 


An invalid options parameter was specified 
with GpiSetPickApertureSize. 


An invalid pick aperture position was 
specified. 

An invalid size parameter was specified 
with GpiSetPickApertureSize. 


An invalid option parameter was specified 
with GpiPlayMetaFile. 


An invalid primitive type parameter was 
specified with GpiSetAttrs or GpiQueryAttrs. 


An invalid size parameter was specified 
with GpiCreatePS or GpiSetPS. 


An invalid format parameter was specified 
with GpiPutData. 


An invalid start parameter was specified 
with DevQueryCaps. 


An invalid rectangle parameter was 
specified. 


PMERR_INV_REGION_CONTROL 
PMERR_INV_REGION_MIX_MODE 
PMERR_INV_REPLACE_MODE_FUNC 
PMERR_INV_RESERVED_FIELD 
PMERR_INV_RESET_OPTIONS 


PMERR_INV_RGBCOLOR 


PMERR_INV_SCAN_START 


PMERR_INV_SEG ATTR 


PMERR_INV_SEG_ATTR_VALUE 
PMERR_INV_SEG_NAME 
PMERR_INV_SEG_OFFSET 
PMERR_INV_SEGLEN 


PMERR_INV_SETID 
PMERR_INV_SHARPNESS_PARM 


PMERR_INV_STOP_DRAW_VALUE 
PMERR_INV_TRANSFORM_TYPE 


PMERR_INV_TYPE 
PMERR_INV_USAGE_PARM 


PMERR_INV_VIEWING_LIMITS 


An invalid control parameter was specified 
with GpiQueryRegionRects. 


An invalid mode parameter was specified 
with GpiCombineRegion. 


An attempt was made to issue GpiPutData 
with the editing mode set to 
SEGEM_REPLACE. 


An invalid reserved field was specified. 


An invalid options parameter was specified 
with GpiResetPS. 


An invalid rgb color parameter was 
specified with GpiQueryNearestColor or 
GpiQueryColor. 


An invalid scanstart parameter was 
specified with a bit-map function. 


An invalid attribute parameter was specified 
with GpiSetSegmentAttrs, 
GpiQuerySegmeniattrs, 
GpiSetlnitialSegmentAttrs, or 
GpiQuerylnitialSegmentAttrs. 


An invalid attribute value parameter was 
specified with GpiSetSegmentAttrs or 
GpiSetinitialSegmentAttrs. 


An invalid segment identifier was specified. 


An invalid offset parameter was specified 
with GpiPutData. 


An order length exceeds the remaining 
segment length in the input PIF. 


An invalid setid parameter was specified. 


An invalid sharpness parameter was 
specified with GpiPolyFilletSharp. 


An invalid value parameter was specified 
with GpiSetStopDraw. 


_ An invalid options parameter was specified 


with a transform matrix function. 
Invalid file-type parameter. 


An invalid options parameter was specified 
with GpiCreateBitmap. 


An invalid limits parameter was specified 
with GpiSetViewingLimits. 
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PMERR_INV_VIEWLIM 
PMERR_INV_XFORM 
PMERR_INV_3DCOORD 


PMERR_INVALID_APPL 
PMERR_INVALID_ARRAY_COUNT 


PMERR_INVALID_ARRAY_SIZE 
PMERR_INVALID_ASCIIZ 


PMERR_INVALID_ATOM 


PMERR_INVALID_ATOM_NAME 
PMERR_INVALID_BUNDLE_TYPE 
PMERR_INVALID_CHARACTER_INDEX 


PMERR_INVALID_CONTROL_DATATYPE 
PMERR_INVALID_DATATYPE 
PMERR_INVALID_DST_CODEPAGE 


PMERR_INVALID_ERRORINFO_HANDLE 
PMERR_ INVALID FLAG 


PMERR_INVALID_FREE_MESSAGE_ID 


PMERR_INVALID_GROUP_HANDLE 
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A set viewing limits order has an 
inconsistent mask and order length in the 
input PIF. 


A set (default) viewing transform order has 
an inconsistent mask and order length in 
the input PIF. 


An order specifying 3-dimensional 
coordinates has been found in the input 
PIF. . 


Attempted to start an application whose 
type is not recognized by OS/2. 


An array has an invalid count, that is, less 
than or equal to zero. 


A control data type array size is invalid. 


The profile string is not a valid 
zero-terminated string. 


The specified atom does not exist in the 
atom table. 


An invalid atom name string was passed. 
An invalid bundie type was passed. 


On WinNextChar or WinPrevChar, a 
character index is invalid, that is, it is less 
than 1 or is greater than the string 
length+1. 


An invalid control data type was specified. 
An invalid data type was specified. 


The destination code page parameter is 
invalid. 


On WinFreeErrorlInfo, the ERRINFO is not 
the handie of an ERRINFO structure, that 
is, it was not created by WinGetErrorinfo. 


An invalid bit was set for a parameter. Use 
constants defined by PM for options, and 
do not set any reserved bits. 


An invalid message identifier was specified. 
The call has completed by assuming the 
message parameter and reply data types to 
be ULONG. 


An invalid program-group handle was 
specified. 


PMERR_INVALID_HACCEL 
PMERR_INVALID_HAPP 
PMERR_INVALID_HATOMTBL 
PMERR_INVALID_HEAP_POINTER 


PMERR_INVALID_HEAP_SIZE 
PMERR_INVALID_HEAP_SIZE_PARM 
PMERR_INVALID_HEAP_SIZE_WORD 
PMERR_INVALID_HENUM 


PMERR_INVALID_HHEAP 
PMERR_INVALID_HMQ 


PMERR_INVALID_HPTR 
PMERR_INVALID_HSTRUCT 


PMERR_INVALID_HWND 
PMERR_INVALID_INI_FILE_HANDLE 


PMERR_INVALID_INTEGER 
PMERR_INVALID_INTEGER_ATOM 


PMERR_INVALID_ MESSAGE_ID 


PMERR_INVALID_NUMBER_OF_PARMS 
PMERR_INVALID_NUMBER_OF_TYPES 


PMERR_INVALID_PARAMETER 


PMERR_INVALID_PARAMETER_TYPE 


An invalid accelerator-table handle was 
specified. 


The application handle passed to 
WinTerminateApp does not correspond to a 
valid session. 


An invalid atom-table handle was specified. 


An invalid pointer was found within the 
heap. 


Invalid data was found within the heap. 
Invalid data was found within the heap. 
Invalid data was found within the heap. 


An invalid enumeration handle was 
specified. 


An invalid heap handle was specified. 


An invalid message-queue handle was 
specified. 


An invalid pointer handle was specified. 


An invalid (null) structure handle was 
specified. 

An invalid window handle was specified. 
An invalid initialization-file handle was 
specified. 

The specified atom is not a valid integer 
atom. 


The specified atom is not a valid integer 
atom. 


A message identifier is invalid. 

The number of parameters is invalid. 
The function call has an invalid number 
(zero) of types. 


An application parameter value is invalid for 
its converted PM type. For example: a 
4-byte value outside the range -32,768 to 
+32,767 cannot be converted to a SHORT, 
and a negative number cannot be 
converted to a ULONG or USHORT. 


A parameter type is invalid for a bundle 
mask. 
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PMERR_INVALID_ PARAMETERS 


PMERR_INVALID_PARAMETERS 
PMERR_INVALID PARM 


PMERR_INVALID_PROGRAM_HANDLE 
PMERR_INVALID_SESSION_ID 


PMERR_INVALID_SRC_CODEPAGE 
PMERR_INVALID STRING_PARM 
PMERR_INVALID_SWITCH_HANDLE 


PMERR_INVALID_TARGET_HANDLE 
PMERR_INVALID_TITLE 
PMERR_INVALID_TYPE_FOR_LENGTH 
PMERR_INVALID_TYPE_FOR_MPARAM 
PMERR_INVALID_TYPE_FOR_OFFSET 


PMERR_INVALID_ WINDOW 


PMERR_KERNING_NOT_SUPPORTED 


PMERR_LABEL_NOT_FOUND 
PMERR_MATRIX_OVERFLOW 


PMERR_MEMORY_ALLOC 
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An application parameter value is invalid for 
its converted PM type. For example: a 
4-byte value outside the range -32768 to | 
+32 767 cannot be converted to a SHORT, 
and a negative number cannot be 
converted to a ULONG or USHORT. 


A parameter to the function contained 
invalid data. 


An invalid program handle was specified. 


The specified session identifier is invalid. 
Either zero (for the application’s own 
session) or a valid identifier must be 
specified. 


The source code page parameter is invalid. 
The specified string parameter is invalid. 


An invalid Window List entry handle was 
specified. 


An invalid target program-group handle was 
specified. 


The specified program or group title is too 
long or contains invalid characters. 


The data type for a control length is invalid. 


The message parameter type for a control 
MPARAM is invalid, that is, not mparam1, 
mparam2 or mreply. 


The data type for a control offset is invalid. 


The window specified with a Window List 
call is not a valid frame window. 


Kerning was requested on 
GpiCreateLogFont call to a presentation 
space associated with a device context that 
does not support kerning. 


The specified element label did not exist. 


An internal overflow error occurred during 
matrix multiplication. This can occur if 
coordinates or matrix transformation 
elements (or both) are invalid or too large. 


An error occurred during memory 
management. 


PMERR_MEMORY_ALLOCATION_ERR 


PMERR_MEMORY_DEALLOCATION_ERR 


PMERR_METAFILE_IN_USE 


PMERR_METAFILE_INTERNAL_ERROR 


PMERR_METAFILE_LIMIT_EXCEEDED 


PMERR_MSG_QUEUE_ALREADY_EXISTS 


PMERR_MSGID_TOO_SMALL 
PMERR_NEGATIVE_STRCOND_DIM 


PMERR_NO_BITMAP_SELECTED 


PMERR_NO_CURRENT_ELEMENT 


PMERR_NO_CURRENT_SEG 


PMERR_NO FILL 


PMERR_NO_METAFILE_RECORD_HANDLE 


PMERR_NO_MSG_QUEUE 
PMERR_NO_PALETTE_SELECTED 


An error occurred during memory 
management. 


An error occurred during memory 
management. 


An attempt has been made to access a 
metafile that is in use by another thread. 


An internal inconsistency has been 
detected during metafile unlock processing. 


The maximum permitted metafile size limit 
was exceeded during metafile recording. 


An attempt to create a message queue for 
a thread failed because a message queue 
already exists for the calling thread. 


The message identifier specified is too 
small. 


A negative array dimension was passed for 
a data type length. 


An attempt has been made to operate ona 
memory device context that has no bit map 
selected. 


An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement 
while there is no currently open element. 


An attempt has been made to issue 
GpiQueryElementType or GpiQueryElement 
while there is no currently open segment. 


No flood fill occurred because either the 
starting point color was the same as the 
input color when a boundary fill was 
requested, or the starting point color was 
not the same as the input color when a 
surface fill was requested. 


The metafile record handle was not found 
during metafile recording, or DevEscape 
(DEVESC_STARTDOC) was not issued 
when drawing to aOD_QUEUED device 
context with a pszDataType field of 
PM_Q_STD. 


An attempt to realize a palette failed 
because no palette was previously selected 
into the Presentation Space. 
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PMERR_NO_SPACE 


PMERR_NOT_CREATED_BY_DEVOPENDC 


PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_DRAGGING 


PMERR_NOT_IN_A_PM_SESSION 
PMERR_NOT_IN_AREA 
PMERR_NOT_IN_DRAW_MODE 
PMERR_NOT_IN_ELEMENT 


PMERR_NOT_IN_IDX 


PMERR_NOT_IN_IMAGE 
PMERR_NOT_IN_PATH 


PMERR_NOT_IN_RETAIN_ MODE 


PMERR_NOT_IN_SEG 


PMERR_NOT_SELF_DESCRIBING_DTYP 
PMERR_OPENING_INI_FILE 
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The limit on the number of Window List 


entries has been reached with 
WinAddSwitchEntry. 


An attempt has been made to destroy a 
device context using DevCloseDC that was 
not created using DevOpenDC. 


An unexpected data format was found in 
the initialization file. 


A drag operation is not in progress at this 
time. 


An attempt was made to access function 
that is only available from PM programs 
from a non-PM session. 


An attempt was made to end an area using 
GpiEndArea or during segment drawing 
while not in an area bracket. 


An attempt was made to issue GpiSavePS 
or GpiRestorePS while the drawing mode 
was not set to DM_DRAW. 


An attempt was made to end an element 
using GpiEndElement or during segment 
drawing while not in an element bracket. 


The application name, key-name or 
program handle was not found. 


An attempt was made to end an image 
during segment drawing while not in an 
image bracket. 


An attempt was made to end a path using 
GpiEndPath or during segment drawing 
while not in a path bracket. 


An attempt was made to issue a segment 
editing element function that is invalid when 
the actual drawing mode is not set to 
retain. 


An attempt was made to end a segment 
using GpiCloseSegment while not in a 
segment bracket. 


A data type is not self-describing. 


Unable to open initialization file (due to lack 
of disk space for example). 


PMERR_ORDER_TOO BIG 


PMERR_OWN_SET_ID_REFS 
PMERR_PALETTE_BUSY 


PMERR_PALETTE_SELECTED 


PMERR_PARAMETER_OUT_OF_RANGE 


PMERR_PATH_INCOMPLETE 


PMERR_PATH_LIMIT_EXCEEDED 
PMERR_PATH_UNKNOWN 
PMERR_PEL_IS_CLIPPED 


PMERR_PEL_NOT_AVAILABLE 


PMERR_PRINTER_DD_NOT_DEFINED 
PMERR_PRINTER_QUEUE_NOT_DEFINED 


PMERR_PRN_ADDR_IN_USE 
PMERR_PRN_ADDR_NOT_DEFINED 
PMERR_PRN_NAME_NOT_DEFINED 
PMERR_PROLOG_ERROR 


An internal size limit was exceeded while 
converting orders from short to long format 
during GpiPutData processing. An order 
was too long to convert. 


An attempt to unload a font failed because 
the setid is still being referenced. 


An attempt has been made to reset the 
owner of a palette when it was busy. 


Color palette operations cannot be 
performed on a presentation space while a 
palette is selected. 


The value of a parameter was not within 
the defined valid range for that parameter. 


An attempt was made to open or close a 
segment either directly or during segment 
drawing, or to issue GpiAssociate while 
there is an open path bracket. 


An internal size limit was exceeded during 
path or area processing. 


An attempt was made to perform a path 
function on a path that did not exist. 


An attempt was made to query a pel that 
had been clipped using GpiQueryPel. 


An attempt was made to query a pel that 
did not exist in GpiQueryPel (for example, a 
memory device context with no selected bit 
map). 


The Presentation Manager device driver 
has not been defined. 


The spooler queue for the printer has not 
been defined. 


A printer is already defined on the port. 
The printer port has not been defined. 
The printer has not been defined. 


A prolog error was detected during drawing. 
Segment prologs are used internally within 
retained segments and also appear in 
metafiles. This error can also arise from an 
End Prolog order that is outside a prolog. 


C-23 


Appendix C. Error Explanations 


PMERR_PS_BUSY 


PMERR_PS_IS_ ASSOCIATED 


PMERR_PS_NOT_ASSOCIATED 
PMERR_QUEUE_TOO_ LARGE 
PMERR_RASTER_FONT 
PMERR_REALIZE_NOT_SUPPORTED 
PMERR_REGION_IS_CLIP_REGION 


PMERR_RESOURCE_DEPLETION 
PMERR_RESOURCE_NOT_FOUND 
PMERR_SEG_AND_REFSEG_ARE_SAME 


PMERR_SEG_CALL_STACK_EMPTY 


PMERR_SEG_CALL_STACK_FULL 


PMERR_SEG_IS_ CURRENT 


PMERR_SEG_NOT_CHAINED 


% 
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An attempt was made to access the 
presentation space from more than one 
thread simultaneously. 


An attempt was made to destroy a 
presentation or associate a presentation 
space that is still associated with a device 
context. 


An attempt was made to access a 
presentation space that is not associated 
with a device context. 


An attempt to create a message queue has 
failed because the value specified for the 
size of the message queue is too large. 


A request was made for the outline of a 
bit-map font. Outlines can only be returned 
for vector font characters. 


An attempt was made to create a realizable 
logical color table on a device driver that 
does not support this function. 


An attempt was made to perform a region 
operation on a region that is selected as a 
clip region. 


An internal resource depletion error has 
occurred. 


The specified resource identity could not be 
found. 


The segid and refsegid specified with 
GpiSetSegmentPriority were the same. 


A call stack empty condition was detected 
when attempting a pop function during 
GpiPop or segment drawing. 


A call stack full condition was detected 
when attempting to call a segment using 
GpiCallSegmentMatrix, attempting to 
preserve an attribute, or during segment 
drawing. 


An attempt was made to issue GpiGetData 
to a segment that was currently open. 


An attempt was made to issue 
GpiDrawFrom, GpiCorrelateFrom or 
GpiQuerySegmenitPriority for a segment 
that was not chained. 


PMERR_SEG_NOT_FOUND 


PMERR_SEG_OVFLOW 


PMERR_SEG_STORE_LIMIT_EXCEEDED 


PMERR_SETID_IN_USE 


PMERR_SETID_NOT_FOUND 


PMERR_SMB_OVFLOW 


PMERR_SOMDD IS ACTIVE 
PMERR_SOMDD_NOT_STARTED 
PMERR_SOURCE_SAME_AS_TARGET 


PMERR_SPL_CANNOT_OPEN_FILE 
PMERR_SPL_DD_NOT_FOUND 


PMERR_SPL_DEVICE_ALREADY_EXISTS 
PMERR_SPL_DEVICE_LIMIT_REACHED 


PMERR_SPL_DEVICE_NOT_INSTALLED 
PMERR_SPL_DRIVER_ERROR 


PMERR_SPL_DRIVER_NOT_INSTALLED 


PMERR_SPL_FILE_NOT_FOUND 
PMERR_SPL_HARD_NETWORK_ERROR 
PMERR_SPL_INI_FILE_ERROR 
PMERR_SPL_INV_DATATYPE 
PMERR_SPL_INV_DRIVER_DATATYPE 


PMERR_SPL_INV_FORMS_CODE 
PMERR_SPL_INV_HSPL 


The specified segment identifier did not 


exist. 


The input PIF has more than 1000 called 
segments. This has overflowed an internal 
buffer. 


The maximum permitted retained segment 
store size limit was exceeded. 


An attempt was made to specify a setid 
that was already in use as the currently 
selected character, marker or pattern set. 


An attempt was made to delete a setid that 
did not exist. 


The input PIF has more than 100 symbol 
sets defined. This has overflowed an 
internal buffer. 


The DSOM daemon is already active. 
The DSOM daemon failed to start. 


The direct manipulation source and target 
process are the same. 


Unable to open the file. 


The Presentation Manager device driver 
definition could not be found. 


The device already exists. 


The limit on the number of devices has 
been reached. 


The device has not been installed. 


No Presentation Manager device driver 
supplied or found. 


The Presentation Manager device driver 
has not been installed. 


Unable to find the file. 

Hard network error. 

Error accessing the initialization file. 
The spool file data type is invalid. 


The data type is invalid for the Presentation 
Manager device driver. 


The forms code for the job is invalid. 


The spooler handle is invalid. 
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PMERR_SPL_INV-JOB_ID 
PMERR_SPL_INV_LENGTH_OR_COUNT 
PMERR_SPL_INV_PRIORITY 
PMERR_SPL_INV_PROCESSOR_DATTYPE 


PMERR_SPL_INV_QUEUE_NAME 
PMERR_SPL_INV_TOKEN 
PMERR_SPL_JOB_NOT_PRINTING 
PMERR_SPL_JOB_ PRINTING 


PMERR_SPL_MANY_QUEUES_ASSOC 
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PMERR_SPL_NO CURRENT _FORMS_CODE 


PMERR_SPL_NO DATA 
PMERR_SPL_NO_DEFAULT_QUEUE 


PMERR_SPL_NO_DISK_SPACE 
PMERR_SPL_NO_FREE_JOB_ID 
PMERR_SPL_NO_MEMORY 
PMERR_SPL_NO_QUEUES ASSOCIATED 


PMERR_SPL_NO _SUCH_LOG ADDRESS 


PMERR_SPL_NOT_AUTHORISED 
PMERR_SPL_PRINT_ABORT 
PMERR_SPL_PRINTER_NOT_FOUND 
PMERR_SPL_PROCESSOR_ERROR 


PMERR_SPL_PROCESSOR_NOT_INST 


PMERR_SPL_QUEUE_ALREADY_EXISTS 
PMERR_SPL_QUEUE_ERROR 
PMERR_SPL_QUEUE_NOT_EMPTY 
PMERR_SPL_QUEUE_NOT_FOUND 


PMERR_SPL_SPOOLER_NOT_INSTALLED 
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The job id is invalid. 
The length or count is invalid. 
The priority for the job is invalid. 


The data type is invalid for the spooler 
queue processor. 


The spooler queue name is invalid. 
The token is invalid. 

The print job is not printing. 

The print job is already printing. 


More than one queue has been associated 
with the printer. 


There is no current forms code defined to 
the Presentation Manager device driver. 


No data supplied or found. 


There is no default spooler queue for the 
printer. 


There is not enough free disk space. 
There is no free job id available. 
There is not enough free memory. 


A queue has not been associated with the 
printer. 


The logical address does not exist (that is, 
it is not defined in the initialization file). 


Not authorized to perform the operation. 
The job has already been aborted. 
The printer definition could not be found. 


No spooler queue processor supplied or 
found. 


The spooler queue processor has not been 
installed. 


The spooler queue already exists. 
No spooler queue supplied or found. 
The spooler queue coniains print jobs. 


The spooler queue definition could not be 
found. 


The spooler is not installed. 


PMERR_SPL_STATUS_STRING_TRUNC 


PMERR_SPL_TEMP_NETWORK_ERROR 
PMERR_SPL_TOO_MANY_OPEN_FILES 
PMERR_SPOOLER_QP_NOT_DEFINED 


PMERR_START_POINT_CLIPPED 
PMERR_STARTDOC_NOT_ISSUED 
PMERR_STARTED_IN_BACKGROUND 


PMERR_STOP_DRAW_OCCURRED 


PMERR_TOO_MANY_METAFILES _IN_USE 


PMERR_TRUNCATED_ORDER 


PMERR_UNABLE_TO_CLOSE_DEVICE 


PMERR_UNCHAINED_SEG_ZERO_INV 


PMERR_UNSUPPORTED_ATTR 


PMERR_UNSUPPORTED_ATTR_VALUE 


PMERR_WIN_DEBUGMSG 


PMERR_WINDOW_LOCK_OVERFLOW 


PMERR_WINDOW_LOCK_UNDERFLOW 


PMERR_WINDOW_NOT_LOCKED 


PMERR_WPDSERVER_IS_ACTIVE 


The print job status string has been 
truncated. 


Temporary network error. 
Too many open files. 


The spooler queue processor has not been 
defined. 


The starting point specified for flood fill is 
outside the current clipping path or region. 


A request to write spooled output without 
first issuing a STARTDOC was attempted. 


The application started a new session in 
the background. 


Segment drawing or GpiPlayMetaFile was 
stopped prematurely in response to a 
GpiSetStopDraw request. 


The maximum number of metafiles allowed 
for a given process was exceeded. 


An incomplete order was detected during 
segment processing. 


Unable to close the print device (for 
example, powered off or offline). 


An attempt was made to open segment 
with segment identifier zero and the 
ATTR_CHAINED segment attribute not 
specified. 

An unsupported attribute was specified in 
the attrmask with GpiSetAttrs or 
GpiQueryAtitrs. 


An attribute value was specified with 
GpiSetAttrs that is not supported. 


Ignore this error. It is reserved for system 
use. 


An overflow occurred for the use count of a 
window. 


An attempt was made to decrement the use 
count of a window below zero. 


The window specified in WinSendMsg was 
not locked. 


The Workplace Shell DSOM Server is 
already active. 
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PMERR_WPDSERVER_NOT_STARTED 


WPERR_INVALID_FLAGS 
WPERR_INVALID_OBJECTID 
-WPERR_INVALID_TARGET_OBJECT 
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The Workplace Shell DSOM Server could 
not be started. 


An invalid flag was specified. 
An invalid object ID was specified. 


An invalid target object was specified. 


Appendix D. Standard Bit-Map Formats 


There are four standard bit-map formats. All device drivers must be able to translate 
between any of these formats and their own internal formats. The standard formats are: 


Bitcount Planes 
1 1 
4 1 
8 1 
24 . 1 


These formats are chosen because they are identical or similar to all formats commonly used 
by raster devices. Only single-plane formats are standard, but it is very easy to convert 
these to any multiple-plane format used internally by a device. 


Bit-Map Data 
The pel data is stored in the bit map in the order that the coordinates appear on a display 
screen. That is, the pel in the lower-left corner is the first in the bit map. Pels are scanned 
to the right, and upward, from that position. The bits of the first pel are stored, beginning 
with the most significant bits of the first byte. The data for pels in each scan line is packed 
together tightly, but all scan lines are padded at the end, so that each one begins on a 
ULONG boundary. 


Bit-Map Information Tables 
Each standard-format bit map must be accompanied by a bit-map information table. 
Because the standard-format bit maps are intended to be traded between devices, the color 
indexes in the bit map are meaningless without more information; for a description of this 
structure, see BITMAPINFO2. 


Some functions use a structure that is similar to BPTPMAPINFO2 but does not have the color 
table array; for a description of this structure, see BITMAPINFOHEADER2. Wherever 
BITMAPINFO2 is shown, BITMAPINFO is also allowed. Similarly, wherever 
BITMAPINFOHEADER2 is shown, BITMAPINFOHEADER is also allowed. 
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Bit-Map Example 


To make the ordering of all the pyle clear, eonsider this simple example of a 5-by-3 array of 
colored pels: 


Red Green Blue Red Green 
Blue Red Green Blue Red 
Green Blue Red Green Blue 


ULONG ExampleBitmap[] { 


0x23 ,0x12,0x30, 0x00 /* bottom line */ 
0x31,0x23,0x10, 0x00 /* middle line */ 
0x12,0x31,0x20, 0x00 /* top line */ 


ie 


#define BLACK OxQ0Q00000L 
#define RED OxOOFFOOOOL 
#define GREEN OxQ0Q0FFOOL 
#define BLUE OxQ00Q00FFL 


struct BitmapInfoTable ExampleInfo = { 


5, /* width */ 
3, /* height */ 
1, /* planes */ 
4, /* bitcount x/ 
BLACK, RED, GREEN, BLUE, /* color table */ 


BLACK, BLACK, BLACK, BLACK, 

BLACK, BLACK, BLACK, BLACK, 

BLACK, BLACK, BLACK, BLACK 
he 


Bit-Map File Format 
The operating system uses the same file format for bit maps, icons, and pointers in resource 
files. In the following description, “bit map” refers to bit maps, icons, and pointers unless 
otherwise specified. 


Two formats are supported. In the first, a single-size version of the bit map is defined. This 
is used whatever the target device. 


The second format allows multiple versions of the bit map to be defined, including one or 
more device-independent versions, and a number of device- “dependent versions, each 
intended for use with a particular device. 


in the case of icons and pointers, when more than one version of the bit map exists, the 
preferred version is one that matches the device size of the icon or pointer; otherwise, the 
device-independent version is used to scale a bit map to the required size. 


The operating system provides pointers that match the requirements of the display device in 
use, typically pointers are 32x32 pels, one bit per plane. 
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Icons provided with the operating system are designed to match the requirements of the 
most common display devices. The following versions of each icon are included in each file: 


32x32 4 bpp (16 color) 
40x40 4 bpp (16 color) 
32x32 1 bpp (black and white) 
20x20 1 bpp (black and white) 
16x16 1 bpp (black and white) 


The 32x32 versions are designed for VGA displays and for device-independent use. 
The 40x40 version is for 8514/A and XGA displays. 
The 20x20 and 16x16 are half-size icons designed for use as mini-icons. 


For general bit maps, which may be of arbitrary size, the preferred version is one matching 
the requested bit map size; otherwise one matching the display size is selected. If neither is 
available, the device-independent version is used from which to scale a bit map. 


For both formats, the definition consists of two sections. The first section contains general 
information about the type, dimensions, and other attributes of the resource. The second 
section contains data describing the pels that make up the bit map(s), and is in the format 
specified in “Bit-Map Data” on page D-1. 


In the multiple-version format, the first section contains an array of 
BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 structures. The format of 
these structures are as follows: 


Heyieaar” struct _BITMAPARRAYFILEHEADER { 
“USHORT. 0 os usType; 
ULONG cbSize; 
ULONG : of fNext; 
USHORT cxDisplay; 
USHORT : cyDisplay; 
BITMAPFILEHEADER —sb fh; 

} BITMAPARRAYFILEHEADER; 


- typedef BITMAPARRAYFILEHEADER *PBITMAPARRAYFILEHEADERS, 


“USHORT 

‘ULONG 
—ULONG — - 

USHORT 

USHORT: 
-BITWAPFILEHEADER2 | 
ok BBITHAPARRAYEILEHEADER2; 


: ‘ypeder BITHAPARRAYTLEHEADE 
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The device-independent version must be the first BTMAPARRAYFILEHEADER or 
BITMAPARRAYFILEHEADER2 defined. 


In the single-size format, the BITMAPARRAYFILEHEADER or 
BITMAPARRAYFILEHEADER2 structure is not present. The definition consists of one or two 
BITMAPFILEHEADER or BITMAPFILEHEADER2 structures. 


The format of the BITMAPFILEHEADER and BITMAPFILEHEADER2 structure are defined 
below: 


typedef struct” _BITWAPFILEHEADER c 
USHORT usType;. 
ULONG = oe ebSizes. 
SHORT xHotspot; 
SHORT yHotspot; 
USHORT ~ of fBits; 
BITMAPINFOHEADER bmp; 

} BITMAPFILEHEADER; 


typedef BITMAPFILEHEADER *PBITMAPFILEHEADER; 


typedef struct _BITMAPFILEHEADER2 { 
| USHORT usType; _ 

- ULONG cbSize; 
SHORT xHotspot; 
SHORT... yHotspot; 

- USHORT > OtfBA ts; 

_ BITMAPINEOHEADER2  bmp2s 

i: } BITMAPF ILEHEADER2; 


‘typeset | BITHWAPFILEHEADER? sPBITMAPFILEHEADER2; 


For icons and pointers, the cy field in bmp is actually twice the pel height of the image that 
appears on the screen. This is because these types actually contain two full bit-map pel 
definitions. The first bit-map definition is the XOR mask, which contains invert information (0 
= no invert, 1 = invert) for the pointer or icon. The second is the AND mask, which 
determines whether the pointer or the screen is shown (0 = black/white, 1 = screen/inverse 
screen). 


For color icons or pointers, there are two bit-maps involved: one that is black and white and 
consists of an AND and an XOR mask, and one that is color that defines the color content. 


The cy field in the BITMAPINFOHEADER2 structure for the color bit- -map must be the real 
height, that is, half the value ene for the black and white bit-map. The cx fields must be 
the same. 
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The following table shows how these two bit-maps are used for a color icon or pointer: 


XOR AND COLOR 

1 1 X Invert screen 
0 0 X Use color x 

0 1 X Transparency 
1 0 x Use color x 


For color icons or pointers, two BITMAPFILEHEADER or BITMAPFILEHEADER2 structures 
are therefore required: 


BITMAPFILEHEADER2 with usType BFT_COLORICON or BFT_COLORPOINTER 
BITMAPINFOHEADER2 (part of BITMAPFILEHEADER2) 
Color table 
BITMAPFILEHEADER2 with same usType 
BITMAPINFOHEADER2 (part of BITMAPFILEHEADERZ) 
Color table 


kk 


bits for one bit-map 
kk 


Kk 


bits for other bit-map 


Kk 


The usType for the first BITMAPFILEHEADER2 is either BFT_COLORICON or 
BFT_COLORPOINTER. This means that a second BITMAPFILEHEADER2 is present as 
part of the definition of a color icon or pointer. The first The first BPTMAPFILEHEADER2 
structure contains the information for the black and white AND and XOR masks, while the 
second BITMAPFILEHEADER2 structure contains the information for the color part of the 
pointer or icon. 


BITMAPFILEHEADER and BITMAPINFOHEADER can occur in place of 
BITMAPFILEHEADER2 and BITMAPINFOHEADER2 in this example. 
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For the multiple version format, the file is as follows: 


BITMAPARRAYFILEHEADER2 for device-independent version 
BITMAPF ILEHEADER2 (part of BITMAPARRAYFILEHEADER2) 
BITMAPINFOHEADER2 (part of BITMAPFILEHEADERZ) 
Color table 


BITMAPFILEHEADER2 ) 
BITMAPINFOHEADER2 ) only if this is a color icon or pointer 
Color table ) 


BITMAPARRAYFILEHEADER2 for first device-dependent version 
BITMAPFILEHEADER2 (part of BITMAPARRAYFILEHEADERZ2) 
BITMAPINFOHEADER2 (part of BITMAPFILEHEADER2) 
Color table 


BITMAPFILEHEADER2 ) 
BITMAPINFOHEADER2 ) only if this is a color icon or pointer 
Color table ) 


Further BITMAPARRAYFILEHEADER2 groups occur here as required 
for additional device-dependent versions 


RK 


bits for one bit-map 
KK 
KK 


bits for next bit-map 
kk 


And so on for as many bit-maps as necessary. 


As before, BITMAPARRAYFILEHEADER, BITMAPFILEHEADER, and 
BITMAPINFOHEADER,, can occur in place of BBPMAPARRAYFILEHEADER2, 
BITMAPFILEHEADER2, and BITMAPINFOHEADER2, 
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Appendix E. Fonts Supplied with the OS/2 Operating 
System 


OS/2* outline fonts and Presentation Manager” bit map fonts are supplied by the operating 
system. 


OS/2 Outline Fonts 
The following Adobe™ Type 1 fonts are supplied with OS/2: 


Family Name Face Name 


Times New Roman* Times New Roman 
Times New Roman Bold 
Times New Roman Bold Italic 
Times New Roman Italic 


Helvetica” Helvetica 
Helvetica Bold 
Helvetica Bold Italic 
Helvetica Italic 


Courier Courier 
Courier Bold 
Courier Bold Italic 
Courier Italic 


The Courier, Tms Rmn, and Swiss family fonts that were supplied with OS/2 release 1.1 and 
1.2 are no longer supplied. Using one of the old names results in one of the new fonts listed 
above being used, as follows: 


Old Family/Face Name Font Used. 
Roman/Tms Rmn Times New Roman 
Swiss/Helv Helvetica 


These fonts are provided in an efficient binary format for use by the OS/2 Adobe Type 
Manager. They are also provided in standard Type 1 format (PFB and AFM) for use with the 
OS/2 PostScript™ printer device driver. 


* Trademark of the IBM Corporation. 
“ Trademarks of Adobe Systems Incorporated, Monotype, and Linotype. 
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Presentation Manager Bit Map Fonts 


The following tables list all system bit map fonts available using the Graphics Programming 
Interface. The first table applies to hardware that does not conform to the International 
Standards Organization (ISO) 9241. (See “International Standards Organization (ISO) 9241” 
on page E-7 for more information on ISO 9241.) The second table lists the fonts supplied 
with OS/2 for IBM hardware that does conform to ISO 9241. 


During system installation, the operating system determines the type of display adapter 
available on your computer and installs only the fonts which match the device resolution. 
Since additional device bit map fonts may be available on specific devices, you may have to 
install the correct bit map fonts if you change your display device after the operating system 
is installed. 


Fonts Supplied for ISO 9241 Non-Conforming Hardware 


E-2 


The following information for each font is included in the table: 


Points _ This is the point size of the font, on a device whose resolution matches that of the 
font, (see “Device” below). 


Ave Wid This is the average width in pels of alphabetic characters weighted according to 
US English letter frequencies. 


Max Wid This is the maximum width in pels of all characters in the font. This field is not 
necessarily the maximum width of any character in the code page. It could be 
used to ensure that the horizontal space allocated on a display or printer is big 
enough to handle any character. 


Height This is the height in pels of the font. This is the minimum number of rows of pels 
needed to output any character of the font on a given baseline. This field may be 
larger than necessary for a given code page. It could be used to ensure that the 
vertical space allocated on a display or printer is big enough to handle any 
character. 


Device This is the X and Y resolution in pels per inch at which the font is intended to be 
used. Only those fonts which match the device resolution of the installed display 
driver are available on the system. If the installed display is changed, the install 
process will reinstall the proper font sets for the new adapter. The IBM devices 
whose device drivers report these resolutions are: 


96 x 48 CGA 

96 x 72 EGA 

96 x 96 VGA and XGA (in 640 x 480 mode) 
120 x 120 8514/A and XGA (in 1024 x 768 mode) 


Note: These values are approximate representations of the actual resolution, 
which in the case of displays depends on which monitor is attached. 
Consequently the point size of characters on the screen is also 
approximate. , 
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The following table applies to hardware that does not conform to ISO 9241. 


Family Face Name Points Av Wid Max Height Device 


oe) 
ols 
= 


96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
20 120x120 
12 10 96x48 
15 25 
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Family Face Name 


Tms Rmn Tms Rmn 
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Device 


120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 
96x96 
4120x120 
96x48 
96x72 
96x96 
120x120 
96x48 
96x72 


Face Name Points Av Wid Max Height Device 
Wid 


96x96 
120x120 


Fonts Supplied for ISO 9241 Conforming Hardware 
The following table lists the fonts and sizes that have been tested and certified as passing 


the ISO 9241 black text on white background criteria for the three IBM displays that conform 
to the standard. These displays are: 


e 9515 - A 14 inch XGA display. 
¢ 9517 - A 17 inch XGA display. 
e 9518 - A 14 inch VGA display. 


See “International Standards Organization (ISO) 9241” on page E-7 for information on ISO 
9241. 


The following information about each font is also included in the table: 


P The point size of the font. 

AW The average character width in pels in the font. 

MW The maximum character width in pels in the font. 

HE The height in pels of the font (maximum baseline extent). 


Device The X and Y resolution in pels per inch on the device the font is intended to be 
used. The IBM devices whose device drivers report these resolutions are: 
96 x 96 VGA and XGA (in 640 x 480 mode) 
120 x 120 XGA (in 1024 x 768 mode) 


P AW MW HE Device 9515 9517 9518 


Courier Courier 8 8 8 13 
ISO 8 10 10 16 


9 8 8 15 
10 10 10 16 
10 12 12 20 
12 12 12 20 
12 15 15 25 
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Family P AW MW HE Device 9515 9517 9518 
Name 


Helv ISO 8 5 13 13 
8 7 14 16 
9 6 13 15 
9 8 20 21 
10 7 14 16 
10 9 20 21 
12 9 17 20 
12 10 21 25 
14 10 21 24, 
14 12 26 29 
18 12 26 29 
18 15 34 36 
24 14 34 36 
19 45 46 


Tms Rmn. Tms Rmn 5 12 13 
ISO 7 15 16 
6 12 15 

7 14 16 

8 17 19 

8 16 19 

10 23 22 

9 23 22 

11 26 27 

11 26 27 

14 34 34 

14 34 34 

17 46 43 


System 8 8 16 
Mono- 10 10 21 
spaced 


See “International Standards Organization (ISO) 9241” on page E-7 for more information on 
ISO 9241. . . . 
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International Standards Organization (ISO) 9241 


ISO 9241 is an international standard covering health and safety in the work place for users 
of visual display terminals. Part 3 of this standard covers clarity and legibility of text 
displayed on computer screens; it places requirements on minimum sizes and luminance 
contrast. The presence of the FM_SEL _ISO9241_TESTED flag in the FONTMETRICS 
structure indicates that the font has been tested for ISO compliance. 


Note: While the fonts were primarily tested for meeting the ISO standard, they have also 
been designed to meet the German standard DIN 66 234. Where the two standards 
differ, the fonts have been designed to meet the stricter requirement. 


The FM_ISO_xxx flags indicate the results of the test on the three IBM* displays that conform 
to the standard. These are the IBM 9515, 9517, and 9518 color displays at the supported 
resolutions of 640 x 480 and 1024 x 768. To determine whether a non-IBM display complies 
with ISO 9241, contact the manufacturer. The current display type can be established using 
VioGetConfig. 


In order for applications to meet the standard, they have to ensure that they use only fonts 
that have been tested and passed. You can determine this by examining the new . 
FM_SEL_I1S09241_TESTED flag in the fsSe/ection parameter in the FONTMETRICS 
structure, the FM_ISO_xxx flags and the sXDeviceRes and sYDeviceRes fields in the 
structure. 


See Appendix E, “Fonts Supplied with the OS/2 Operating System” on page E-1 for the 
table describing ISO 9241 compliant fonts. 


* Trademark of IBM Corporation. 
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Appendix F. Format of Interchange Files 


A metafile is a file in which graphics are stored. The file is application-created, and it 
contains the graphics orders generated from those GPI calls that are valid in a metafile. 
Metafiled graphics can be reused by the application that created them. They can also be 
made available to other applications at the same, or at a different, workstation. 


This section describes the restrictions which apply when generating the metafile and gives 
detail of the overall structure. For the graphics orders descriptions, see “Graphics Orders” in 
the Graphics Programming Interface Programming Reference. 


Metafile Restrictions 


The following restrictions apply to the generation of all metafiles, and also to the generation 
of a PM_Q_STD print file to a OD_QUEUED device: 


¢ If GpiWCBitBIt or GpiBitBit is used to copy a bit map to a device context in an 
application, the application should not delete that bit map handle with GpiDeleteBitmap 
before the device context is closed (metafile is closed). 


¢ GpiSetPS must not be used. 
e¢ GpiSetPageViewport is ignored. 


The following section lists some general rules that must be followed when creating a metafile 
that is to be acceptable to SAA-conforming implementations, or replayed into a presentation 
space that is in draw-and-retain or retain mode (see “GpiSetDrawingMode” in Graphics 
Programming Interface Programming Reference). 


e These items must be established or defaulted before any drawing occurs to the graphics 
presentation space, and not changed subsequently: 


— The graphics field (GpiSetGraphicsField). For an SAA-conforming metafile, the 
graphics field must be defaulted or set to no clipping. 

— The code page for the default character set (GpiSetCp). 

— The color table or palette (GpiCreateLogColorTable or GpiCreatePalette). The size 
of the color table must not exceed 31KB (KB equals 1024 bytes). 

— The default viewing transform (GpiSetDefaultViewMatrix). 

— The setting of the draw controls (GpiSetDrawControl). DCTL_DISPLAY must be 
defaulted or set ON. 

— The default values of attributes (see “GpiSetDefAttrs” in the Graphics Programming 
Interface Programming Reference), viewing limits (see “GpiSetDefViewingLimits” in 
the Graphics Programming Interface Programming Reference), primitive tag (see 
“GpiSetDefTag’ in the Graphics Programming Interface Programming Reference) 
and arc parameters (see “GpiSetDefArcParams’ in the Graphics Programming 
Interface Programming Reference). . 
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e These calls should not be used: 


— GpiBitBit 

— GpiDeleteSetld (note that this means that local identifiers cannot be used again 
within the picture) 

— GpiErase 

— GpiExcludeClipRectangle 

— GpilntersectClipRectangle 

— GpiOffsetClipRegion 

— GpiPaintRegion 

— GpiResetPS 

— GpiSetClipRegion 

— GpiSetPel 

— GpiSetPS 

— DevEscape (for an escape which is metafiled). 


e GpiCreateLogFont must not redefine a local identifier that has previously been used 
within the picture. 


e The metafile context must not be reassociated. 


e Ifa bit map is used as the source of a GpiWCBIitBIt operation, or as an area-fill pattern, 
it must not be modified or deleted (GpiDeleteBitmap) before the metafile is closed. 


e Only these foreground mixes must be used (see “GpiSetMix’” in the Graphics 
Programming Interface Programming Reference): 


— FM_DEFAULT 

— FM_OR 

— FM_OVERPAINT 
— FM_LEAVEALONE 


e Only these background mixes must be used (see “GpiSetBackMix’” in the Graphics 
Programming Interface Programming Reference): 


— BM_DEFAULT 
— BM_OVERPAINT 
— BM_LEAVEALONE 


e If palettes are used (see “GpiCreatePalette” in the Graphics Programming Interface 
Programming Reference): the palette that is metafiled is the one in force when the 
metafile device context is dissociated from the (final) presentation space. If the palette is 
changed during the course of the picture (using GpiSetPaletteEntries), it must therefore 
only be with incremental additions. 


Note: There is no restriction concerning the use of primitives outside segments. nese: are 
metafiled in segment(s) with zero identifier. 
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Metafile Data Format 


This section describes the format of the data in a metafile, as it would be stored in an OS/2* 
disk file. 


Metafile data is stored as a sequence of structured fields. Each structured field starts with 
an eight-byte header consisting of a two-byte /ength field and a three-byte identifier field. 
These are followed by a one-byte flags field and a two-byte segment sequence number field. 


The length field contains a count of the total number of bytes in the structured field, including 
the length field. The identifier field uniquely identifies the type of the structured field. 


The flags and segment sequence number fields are always zero. 


Following the header are positional parameters that are optional and dependent on the 
particular structured field. 


Following the positional parameters are non-positional parameters called triplets. These are 
self-defining parameters and consist of a one-byte /ength field, followed by a one-byte 
identifier field, followed by the data of the parameter. 


The length field contains a count of the total number of bytes in the triplet, including the 
length and identifier fields. The identifier field identifies uniquely the type of the triplet. 


A metafile is structured into a number of different functional components; for example, 
document and graphics object. Each component comprises a number of structured fields, 
and is delimited by “begin-component’ and “end-component” structured fields. Structured 
fields marked as required, inside an optional structured field bracket, are required if the 
containing bracket is present. 


The graphics orders that describe a picture occur in the graphics data structured field. See 
“Structured Field Formats” on page F-4 for more information. 


* Trademark of IBM Corporation 
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Structured Field Formats 


The format of the various structured fields is given below: 


Begin Document 


Structured Field Introducer (BDT): required 


0-1 

2-4 
5 

6-7 


Parameters 


0-7 
8 
9 


Length Oxn+1E 

BDT 0xD3A8A8 

Flags 0x00 

Segment sequence number 0x0000 


Document name C'0000 0001' 
Architecture version 0x00 
Document security 0x00 


Triplets (all required) 


2-n 


Length 0x05 

Triplet Id 0x18 . 
Interchange set type 0x03 (resource document) 
Base set definition Ox0C00 (level 12, version 0) 


Length 0x06 
Triplet Id 0x01 
GCID 


Length Oxn+1 


‘Triplet Id 0x65 


Comment, used for metafile description of up to 252 bytes. 


Begin Resource Group (BRG): required 


Structured Field Introducer 


0-1 
2-4 


Parameters 


0-7 


Length 0x0010 

BRG OxD3A8C6 

Flags 0x00 

Segment sequence number 0x0000 


Resource group name C'0000 0002' 
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Begin Color Attribute (BCA) Table: required 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 BCA 0xD3A877 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Color table name C'0000 0004' 


Color Attribute Table (CAT): required 


Structured Field Introducer 


0-1 Length Oxn+8 

2-4 CAT 0xD3B077 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 


Base Part (required) 


0 Flags 
0 Reserved B'0' 
1 Reset 


B'O' Do not reset to default 
B'1' Do reset to default 
2-7 Reserved B'000000' 
1 Reserved 0x00 
2 LCTID 0x00 


Element list(s) (triple generating) are mutually-exclusive. One or other is required. 


Element List (repeating) 


0 Length of this parameter 
1 Type 0x01: element list 
2 Flags 0x00: reserved 
3 Format 

0x01 RGB 
4-6 Starting Index 


(Top Byte Truncated) 


7 Size of RGB component 0x08 

8 Size of RGB component2 0x08 

9 Size of RGB component3 0x08 

10 = ~—~—«~*Numbeer of bytes in each following color triple 0x04 
11-m Color triples 
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Triple Generating 


0 - Length of this parameter 0x0A 
1 Type 0x02: bit generator 
2 Flags 

0 ABFlag 

B'O' Normal 

1-7 Reserved B'0000000' 
3 -Format 

0x01 RGB 

4-6 Starting index (top byte truncated) 

a § Size of RGB component1 0x08 

8 Size of RGB component2 0x08 © 
9 Size of RGB component3 0x08 


End Color Attribute (ECA) Table: required 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 ECA 0xD3A977 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Color table name C'0000 0004' 


Begin Image Object (BIM): optional, repeating 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 BIM 0xD3A8FB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Image name C'xxxx xxxx' 


Begin Resource Group (BRG): optional 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 BRG 0xD3A8C6 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7. Resource group name C'xxxx xxxx' 
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Color Attribute Table (BCA): optional 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 BCA 0xD3A877 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Color table name C'xxxx xxxx' 


Color Attribute Table (CAT): required 


Structured Field Introducer 


0-1 Length 

2-4 CAT 0xD3B077 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

Base Part 

0 Flags 0x00 

1 Reserved 0x00 

2 LUTID 


Element List (repeating) 


0 Length of this parameter 
1 Type 0x01: element list 
2 Flags 0x00: reserved 

3 Format 0x01: RGB 

4-6 Starting index 


(top byte truncated) 


7 Size of RGB component1 0x08 

8 Size of RGB component2 0x08 

9 Size of RGB component3 0x08 

10 Number of bytes in each following color triple 0x03 
11-n Color triples 


End Color Attribute Table (ECA): required if BCA present 


- Structured Field Introducer 


0-1 ‘Length 0x0010 

2-4 ECA 0xD3A977 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
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F-7 


Parameters 


0-7 Color Table name C!xxxx xxxx' 


End Resource Group (ERG): required if BRG present 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 ERG OxD3A9C6 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Resource Group name C'xxxx xxxx' 


Begin Object Environment Group (BOG): optional 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 BOG 0xD3A8C7 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Object environment group name C'xxxx xxxx' 


Map Color Attribute (MCA) Table: required 


Structured Field Introducer 


0-1 Length Ox001A 

2-4 MCA 0xD3AB77 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-1 Length 


Triplet (required) 


0 Length 0x0C 
1 Triplet type: fully qualified name 0x02 
2 Type: ref to Begin Resource Object 0x84 
3 - ID 0x00 
4-11 Color table name C'xxxx xxxx' 
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Icid (required) 


0 Length 0x04 

1 Triplet type: resource local ID 0x24 
2 Type color table resource 0x07 

3 Local identifier (LUT-ID) 0x01 


End Object Environment Group (EOG): required if BOG present 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 EOG 0xD3A9C7 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters. 

0-7 Object Environment Group name C'xxxx xxxx' 


image Data Descriptor (IDD): required 


Structured Field Introducer 


0-1 Length 0x0011 

2-4 IDD 0xD3A6FB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0 Unit of measure: 


0x00 _ tens of inches 
0x01 tens of centimeters 


1-2 X resolution image points / VOM 
3-4 Y resolution image points / VOM 
5-6 X extent of image PS 
7-8 Y extent of image PS 


Image Picture Data (IPD): required 


Structured Field Introducer 


0-1 Length 

2-4 IPD 0xD3EEFB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 


Parameters (all required and in this order, except that only one of Image LUT-ID and 
IDE structure is present) 
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Begin Segment 


0 Type 0x70: begin segment 
1 Length of following 0x00 


Begin Image Content 


0 Type 0x91: Begin Image Content 
1 Length of following 0x01 

2 Format OxFF 

Image Size 

0 Type 0x94: image size 

1 Length of following 0x09 

2 Units of measure 0x02: logical 
3-4 Horizontal resolution 

5-6 Vertical resolution 

7-8 - Height in pels 

9-10 Width in pels 


Image Encoding 


0 Type 0x95: image encoding 

1 Length of following 0x02 

2 Compression algorithm 0x03: none 

3 Recording algorithm 0x03: bottom-to-top 
Image IDE-Size 

0 Type 0x96: image IDE-Size 

1 Length of following 0x01 

2 Number of bits per element 


Image LUT-ID (For bit maps with other than 24 bits per pel) 


0 Type 0x97 Image LUT-ID 
1 Length of following 0x01 
2 LUT-ID 


IDE Structure (For bit maps with 24 bits per pel) 


0 Type Ox9B: IDE structure 
1 Length of following 0x08 
2 Flags: 

0 ABFlag 


B'O'§ Normal (Additive) 
1-7 Reserved B'0000000' 
3 Format 
0x01 RGB 
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4-6 Reserved 0x000000 
Size of element 1 
Size of element 2 
Size of element 3 


oon 


Image Picture Data (IPD): required, repeatin 


Structured Field Introducer 


0-1 Length 

2-4 IPD 0OxD3EEFB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

Image Data 

0-1 Type OxFE92: image data 

2-3 Length of following 

4-n Image data (scan lines of bit maps) 


End Image Content (required, only present in last Image Picture Data) 


0 Type 0x93: End Image Content 
1 Length of following 0x00 


End Segment (required, only present in last Image Picture Data) 


0 Type 0x71: end segment 
1 Length of following 0x00 


End Image Object (EIM): required if BIM present 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 EIM 0xD3A9FB 

5 Flags 0x00 : 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Image name C'xxxx Xxxx' 


Begin Graphics Object (BGR): required 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 BGR 0xD3A8BB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
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Parameters 
0-7 Graphics object name C'0000 0007’ 


Begin Object Environment Group (BOG): optional 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 LOG 0xD3A8C7 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Object Environment Group name C'0000 0007’ 


Map Color Attribute Table (MCA): required 


Structured Field Introducer 


0-1 Length 0x0016 

2-4 MCA 0xD3AB77 

5 Flags 0x00 . 
6-7 Segment sequence number 0x0000 
Parameters 

0-1 Length 


Triplet (required) 


0 Length 0x0C 

1 Triplet type: fully qualified name 0x02 

2 Type: ref to Begin Resource Object 0x84 
3 ID 0x00 | 

4-11 Color table name C'0000 0004' 


Map Coded Font (MCF): required, for default font 


Structured Field Introducer 


0-1 Length 0x20 

2-4 MCF 0xD3AB8A 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-1 Length 


Triplets (required) 
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Font name 


0 Length 0x0C 

1 Triplet type: fully qualified name 0x02 
2 Type: ref to coded font 0x84 

3 iD 0x00 

4-11 Coded font name: C'nnxx xxxx' 


where n is OxFF 


icid 

0 Length 0x04 

1 Triplet type: Resource Local ID 0x24 
2 Type: Coded Font Resource 0x05 

3 Local identifier (CID) 0x00 


Font Binary GCID 


0 Length 0x06 
1 Triplet type: Font Binary GCID 0x20 
2-5 GCID 


Map Coded Font (MCF): optional, repeating, for loaded fonts 


Structured Field Introducer 


0-1 Length 0x58 

2-4 MCF 0xD3AB8A 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-1 Length 


Triplets (required) 


Font name 

0 Length 0x0C 

1 Triplet type: fully qualified name 0x02 
2 Type: ref to coded font 0x84 

3 ID 0x00 

4-11 Coded font name 

Icid 

0 Length 0x04 

1 Triplet type: Resource Local ID 0x24 
2 Type: coded font resource 0x05 

3 Local identifier (LCID) 
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Font Attributes 


0 Length 0x14 

1 Triplet type: Font Descriptor 0x1F 
2 Weight Class 
3 Width Class 
4-5 Font Height 
6-7 Char Width 

8 Descript Flags 
9 Usage Codes 
10 Family 

11 ~ Activity Class 
12 Font Quality 
13-14 CAP Height 
15-16 X Height 
17-18 Line Density 
19 Use Flags 


Font Binary GCID 


0 Length 0x06 

1 Triplet type: Font Binary GCID 0x20 
2-5 GCID 

Font Typeface 

0 Length 0x24 

1 Triplet type: fully qualified name 0x02 
2 Type: ref to font typeface 0x08 

3 ID 0x00 

4-35 Font typeface C'xxx..xxx' 


Map Data Resource (MDR): optional, repeating 


Structured Field Introducer 


0-1 Length 0x1D 

2-4 MDR O0xD3ABC3 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

se Length 


Triplets (required) 


Bit-map Name 


0 Length 0x0C 
1 Triplet type: fully qualified name 0x02 
2 Type: ref to Image Object 0x84 
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3 ID 0x00 
4-11 Image name C'xxxx Xxxx' 


Extended Resource Icid 


0 Length 0x07 

1 Triplet type: Extended Resource Local ID 0x22 
2 Type: Image Resource 0x10 

3-6 Bit-map handle 


End Object Environment Group (EOG): required if BOG present 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 EOG 0xD3A9C7 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Object Environment Group name C'0000 0007' 


Graphics Data Descriptor (GDD): required 


Structured Field Introducer 


0-1 Length Oxnnnn 

2-4 GDD 0xD3A6BB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 


Parameters (all required and in this order) 


0 OxF7 Specify GVM Subset 
1 Length of following data 0x07 
2 OxBO drawing order subset 
3-4 0x0000 
5 0x23 Level 3.2 
6 0x01 Version 1 
7 Length of following field 0x01 
8 Coordinate types in data 
0x04 Intel16 
0x05 Intel32 


OxF6 Set Picture Descriptor 


1 Length of following data 
2 Flags 
0 B'0' Picture in 2D 
- 4 Picture Dimensions 


B'0' Not absolute (PU_ARBITRARY PS) 
B'1' Absolute (example: PU_TWIPS PS) 
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2 Picture Elements 
B'O' Not pels 
B'1' Pels (PU_PELS PS) 
(Bit 1 must also be set) 


3-7 B'00000' 

3 0x00 Reserved 

4 Picture frame size coordinate type 
0x04 _ = inteli6 
0x05 Intel32 

5 UnitsOfMeasure 


-0x00 Ten inches 
0x01 Decimeter 
6-11 or 6-17 (2 or 4 bytes) Resolution. 
GPS Units / VOM on x axis 
GPS Units / UOM on y axis 
GPS Units / UOM on z axis 
12-23 or 18-41 (2 or 4 bytes) Window Size. 
GPS X left, X right 
GPS Y bottom, Y top 
GPS Z near, Z far 


0x21 Set Current Defaults 
Length of following data 
Set Default Parameter Format 0x08 
Mask 0xE000 
Names Ox8F 
Coordinates 
0x00 Picture in 2D 
7 Transforms 
0x04 = Inteli6 
0x05 = Intel32 
8 Geometrics 
0x04 ‘Inteli6 
0x05 = Intel32 


Onan =o 
& 


0 0x21 Set Current Defaults 

1 Length of following data 

2 Set default viewing transform 0x07 

3-4 Mask 0xCCOC 

5 Names Ox8F 

6-n M11, M12, M21, M22, M41, M42 Matrix elements 


0 0x21 Set Current Defaults 

1 Length of following data 

2 Set default line attributes 0x01 

3-4 Mask - OR of as many of the following bits as are required: 
0x8000 Line type 
0x4000 Line width 
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0x2000 Line end 

0x1000 Line join 

0x0800 Stroke width 

0x0008 Line color 

0x0002 Line mix 

Flags 

OxOF Set indicated default attributes to initial values. (Data field is not present 
in this instance). 

Ox8F Set indicated default attributes to specified values. 

Data — data values as required, in the following order if present. 

No space is reserved for attributes for which the corresponding mask flag was 

not set. 

(1 byte) - Line type 

(1 byte) - Line width 

(1 byte) - Line end 

(1 byte) - Line join 

(G bytes) - Stroke width 

(4 bytes) - Line color 

(1 byte) - Line mix 

(G=2 or 4 depending on the Geometrics parameter of Set Default Parameter 

Format) 


0x21 Set Current Defaults 

Length of following data 

Set Default Character Attributes 0x02 

Mask — OR of as many of the following bits as are required: 

0x8000 Character angle 

0x4000 Character box 

0x2000 Character direction 

0x1000 Character precision 

0x0800 Character set 

0x0400 Character shear 

0x0040 Character break extra 

0x0020 Character extra 

0x0008 Character color 

0x0004 Character background color 

0x0002 Character mix 

0x0001 Character background mix 

Flags 

OxOF Set indicated default attributes to initial values. (Data field is not present in 
this case). 

Ox8F Set indicated default attributes to specified values. 

Data - data values as required, in the following order if present. 

No space is reserved for attributes for which the corresponding Mask flag was 

not set. 


(2*G bytes) - Character angle 
(2*G +4 bytes)  - Character box 
(1 byte) - Character direction 
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(1 byte) - Character precision 


(1 byte) - Character set 

(2*G bytes) - Character shear 

(4 bytes) - Character break extra 

(4 bytes) - Character extra 

(4 bytes) - Character color 

(4 bytes) - Character background color 

(1 byte) - Character mix 

(1 byte) - Character background mix 

(G=2 or 4 depending on the Geometrics parameter of Set Default Parameter 
Format) 


0x21 Set Current Defaults 
Length of following data 
Set Default Marker Attributes 0x03 
3-4 Mask - OR of as many of the following bits as are required: 
0x4000 Marker box . 
0x1000 Marker precision 
0x0800 Marker set 
0x0100 Marker symbol 
0x0008 Marker color 
0x0004 Marker background color 
0x0002 Marker mix 
0x0001 Marker background mix 
5 Flags 
~ QxOF Set indicated default attributes to initial values. 
(Data field is not present in this instance) 
Ox8F Set indicated default attributes to specified values. 


N= © 


6-n Data - data values as required, in this order if present. 
No space is reserved for attributes for which the corresponding Mask flag was 
not set. 
(2*G bytes) - Marker box 
(1 byte) - Marker precision 
(1 byte) - Marker set 
(1 byte) - Marker symbol 
(4 bytes) - Marker color 
(4 bytes) - Marker background color 
(1 byte) - Marker mix 
(1 byte) - Marker background mix 
(G=2 or 4 depending on the Geometrics parameter of Set Default Parameter 
Format) 


0x21 Set Current Defaults 
1 Length of following data 
Set Default Pattern Attributes 0x04 
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Mask - OR of as many of the following bits as are required: 

0x0800 Pattern set 

0x0100 Pattern symbol 

0x0080 Pattern reference point 

0x0008_ Pattern color 

0x0004 Pattern background color 

0x0002 Pattern mix 

0x0001 Pattern background mix 

5 Flags 
OxOF Set indicated default attributes to initial values. 

(Data field is not present in this instance) 

Ox8F Set indicated default attributes to specified values. 

6-n Data - data values as required, in this order if present. 
No space is reserved for attributes for which the corresponding Mask 
flag was not set. 


(1 byte) - Pattern set 

(1 byte) - Pattern symbol 

(2*G bytes) - Pattern reference point 
(4 bytes) - Pattern color 

(4 bytes) - Pattern background color 
(1 byte) - Pattern mix 

(1 byte) - Pattern background mix 


(G=2 or 4 depending on the Geometrics parameter of Set Default 
Parameter Format) 


0x21 Set Current Defaults 
Length of following data 
Set Default Image Attributes 0x06 
4 Mask - OR of as many of these bits as are required: 
0x0008 _ Image color 
0x0004 Image background color 
0x0002 Image mix 
0x0001 Image background mix 
5 Flags 
OxOF Set indicated default attributes to initial values. (Data field is 
not present in this instance) 
Ox8F Set indicated default attributes to specified values. 
6-n Data - data values as required, in this order if present. 
No space is reserved for attributes for which the corresponding Mask 
flag was not set. 


QN—_o 


(4 bytes) - Image color 
(4 bytes) - Image background color 
(1 byte) - Image mix . 
(1 byte) - Image background mix 
0 0x21 Set Current Defaults 
1 Length of following data 
2 Set Default Viewing Window 0x05 
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3-4 Mask - OR of as many of the following bits as are required: 
0x8000 x left limit 
0x4000_ x right limit 
0x2000 si» bottom limit 
0x1000 =>» top limit 

5 Flags 
OxOF Set indicated default attributes to initial values. 

(Data field is not present in this case). 
Ox8F Set indicated default attributes to specified values. 

6-n Data - data values as required, in the following order if present. 
No space is reserved for attributes for which the corresponding Mask 
flag was not set. 

(2*G bytes) - x left limit 

(2*G bytes) - X right limit 

(2*G bytes) - y bottom limit 

(2*G bytes) - y top limit 

(G=2 or 4 depending on the Geometrics parameter of Set Default 
Parameter Format) 


0x21 Set Current Defaults 

Length of following data 

Set Default Arc Parameters 0x0B 
-4 Mask - OR of as many of the following bits as are required: 

0x8000 P value 

0x4000 Q value 

0x2000 _ R value 

0x1000 S value 
5 Flags 

OxOF Set indicated default attributes to initial values. 
(Data field is not present in this case). 
Ox8F Set indicated default attributes to specified values. 

6-n Data - data values as required, in the following order if present. 
No space is reserved for attributes for which the corresponding Mask 
flag was not set. | 
(G bytes)  -P value 
(G bytes) - Q-value 
(Gbytes) -R value 
(Gbytes) -S value 
(G=2 or 4 depending on the Geometrics parameter of Set Default 
Parameter Format) 


Ono 


0x21 Set Current Defaults 
Length of following data 
Set Default Pick Identifier OxOC 
“4 Mask - OR of as many of the following bits as are required: 
0xs000 ‘Pick identifier 


On — © 
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5 Flags 
OxOF Set indicated default attributes to initial values. 
(Data field is not present in this case). 
Ox8F Set indicated default attributes to specified values. 
6-n Data - data values as required, in the following order if present. 
No space is reserved for attributes for which the corresponding Mask 
flag was not set. 
(4 bytes) - Pick identifier 


OxE7 Set Bit-map Identifier 


1 Length of following data 0x07 
2-3 Usage Flags 0x8000 

4-7 Bit-map handle 

8 Lcid 


Graphics Data (GAD): optional, repeating 


Structured Field Introducer 


0-1 Length Oxn+9 

2-4 GAD 0xD3EEBB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 


Parameters (maximum length in one structured field is 32759) 
Graphics Segment (optional, repeating) 


Segment data (including the Begin Segment parameter) can be split at any point between 
successive Graphics Data structured fields. 


0 0x70 Begin Segment 

1 Length of following data Ox0E 
2-5 Segment identifier 

6 Segment attributes (1) 


0 B'1' Invisible 

1 B'1' Propagate invisibility 

2 B'1' Detectable 

3 B'1' Propagate detectability 
6 B'1' Dynamic 

7 B'1' — Fast chaining 


7 Segment attributes (2) 
0 B'T' Non-chained 
3B'1' Prolog 

8-9 Segment data length (low-order 2 bytes) 

10-13 Reserved 

14-15 Segment data length (high-order 2 bytes) 

16-n Graphics orders (see the Graphics Programming Interface Programming 
Reference) 
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End Graphics Object (EGR) 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 EGR 0xD3A9BB 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Graphics object name C'0000 0007' 


End Resource Group (ERG): required 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 ERG 0xD3A9C6 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 

0-7 Resource Group name C'0000 0002' 


End Document (EDT): required 


Structured Field Introducer 


0-1 Length 0x0010 

2-4 EDT OxD3A9A8 

5 Flags 0x00 

6-7 Segment sequence number 0x0000 
Parameters 


0-7 Document name C'0000 0001' 
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Appendix G. Initialization File Information 


Initialization files include information about printers, queues, and system preferences set by 
the user from the control panel. Applications can query this information by using the 
PrfQueryProfileData, PrfQueryProfileInt, PrfQueryProfileSize, and PrfQueryProfileString 
functions. 


All data in initialization files is accessed by a two-level hierarchy of application name, and 
key name within an application. Presentation Manager system data is keyed off 
“applications” that have names starting with PM_. 


The application name/key name combinations that applications may need to use are listed 
below, together with the definition of the corresponding data. 


Note: Information that is prefixed with PM_SPOOLERxxxx can not always be modified 
directly: The spooler validates all attempts to write information to the INI file that it 


depends on. 

Application name “PM_ControlPanel” 

Key name “Beep” 

Type integer 

Content/value 1 or 0. 

Application name “PM_ControlPanel” 

Key name “LogoDisplayTime” 

Type integer 

Content/value -1 < time < 32767 milliseconds. 
Indefinite display -1 
No display 0 
Timed display >0 


Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 


Application name 
Key name 


Type 
Content/value 
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“PM_ControlPanel” 
“cxDoubleClick” 

integer 

SV_CXDBLCLK size in pels. 


“PM_ControlPanel” 
“cyDoubleClick” 

integer 

SV_CYDBLCLK size in pels. 
“PM_ControlPanel” 


“cxMotionStart” 
integer 


SV_CXMOTIONSTART size in pels. 


“PM_ControlPanel” 
“cyMotionStart” 
integer 


SV_CYMOTIONSTART size in pels. 
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Application name “PM_National” 


Key name “jCountry” 

Type integer 

Content/value country code:. 

Arabic 785 

Australian 61 
Belgian 32 
Canadian-French 2 
Danish 45 
Finnish 358 
French —_ 33 
German 49 
Hebrew 972 
Italian 39 
Japanese 81 
Korean 82 
Latin-American 3 
Netherlands | 31 
Norwegian 47 
Portuguese 351 
Simpl. Chinese 86 
Spanish 34 
Swedish 46 
Swiss 41 
Trad. Chinese 88 
UK-English 44 
US-English 1 
Other country 0. 

Application name “PM_National” 

Key name “iDate” 

Type integer 

Content/value 0=MDY; 1=DMY; 2=YMD. 

Application name “PM_National” 

Key name “iCurrency” 

Type integer 

Content/value Values have the following meanings: 


0 —s—~ Prefix, no separator 
1 Suffix, no separator 
2 Prefix, 1 character separator 
3 Suffix, 1 character separator. 


Application name “PM_National” 

Key name “iDigits” 

Type integer 

Content/value n = number of decimal digits. 
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Application name 
Key name 

Type 
Content/vaiue 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 
Application name 
Key name 

Type 
Content/value 


“PM_National” 

“iTime” 

integer 

0 = 12-hour clock; 1 = 24-hour clock. 


“PM_National” 

“iLzero” 

integer 

0 = no leading zero; 1 = leading zero. 


“PM_National” 

“s1159” 

string 

“am’ for example. 3 chars max. 


“PM_National” 

“$2359” 

string 

“pm” for example. 3 chars max. 


“PM_National” 

“sCurrency” 

string 

“$” for example. 3 chars max. 


“PM_National” 

“s Thousand” 

string 

“,” for example. 1 char max. 


“PM_National” 

“sDecimal” 

string | 

“” for example. 1 char max. 


“PM_National” 

“sDate” 

string 

“[’ for example. 1 char max. 


“PM_National” 

“sTime” 

string 

“”” for example. 1 char max. 
“PM_National” 

“sList” 

string 

“.” for example. 1 char max. 
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Application name 
Key name 

Type 
Content/value 


Application name. 


Key name 
Type 
Content/value 


Application name 
Key name 

Type 
Content/value 


PM_Fonts 

<Font module name> 

string ; 

fully-qualified drive:\path\filename.ext. 


“PM_SPOOLER’” 
“QUEUE” 

string 

<Queue name>; 


where: <Queue name> is the name of the default queue (might 
be NULL). This must be a key name for the 
PM_SPOOLER_QUEUE application. 


“PM_SPOOLER” 
“PRINTER” 
string 

<Printer name>; 


where: <Printer name> is the name of the default printer (might 
be NULL). 


Note: Use the SpilQueryDevice and SpiQueryQueue functions to retrieve the spooler 


configuration data. 
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Appendix H. Virtual Key Definitions 


The PC VKEY set is shown in the following table: 


VK_BUTTON1 
VK_BUTTON2 
VK_BUTTON3 


VK_BREAK 
VK_BACKSPACE 
VK_TAB 
VK_BACKTAB 
VK_NEWLINE 
VK_SHIFT * 
VK_CTRL * 
VK_ALT * 
VK_ALTGRAF * 
VK_PAUSE 
VK_CAPSLOCK 
VK_ESC 
VK_SPACE * 
VK_PAGEUP * 
VK_PAGEDOWN * 
VK_END * 
VK_HOME * 
VK_LEFT * 
VK_UP * | 
VK_RIGHT * 
VK_DOWN * 
VK_PRINTSCRN 
VK_INSERT * 
VK_DELETE * 
VK_SCRLLOCK 
VK_NUMLOCK 
VK_ENTER 
VK_SYSRQ 
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Personal Computer AT Keyboard 


These values are only used to 
access the up/down and toggled 
states of the pointing device 
buttons; they never actually 
appear in a WM_CHAR message. 


Ctrl + Scroll Lock 


Backspace 


Tab 

Shift + Tab 

Enter 

Left and Right Shift 
Ctrl 

Alt 

None 

Ctrl + Num Lock 
Caps Lock 

Esc 

Space 

Numpad 9 
Numpad 3 
Numpad 1 

Numpad 7 
Numpad 4 
Numpad 8 
Numpad 6 
Numpad 2 

Shift + Print Screen 
Numpad 0 
Numpad &bd. 
Scroll Lock 

Num Lock 

Shift + Enter 
SysRq 


' Enhanced Keyboard 


These values are only used to 
access the up/down and toggled 
states of the pointing device 
buttons; they never actually 
appear ina WM_CHAR message. 


Ctrl + Pause 
Backspace 

Tab 

Shift + Tab 

Enter 
Left and Right Shift 
Left and Right Ctrl 
Left and Right Alt 

Alt Graf (if available) 
Pause 

Caps Lock 

Esc 

Space 

Pg Up and Numpad 9 
Pg Dn and Numpad 3 
End and Numpad 1 
Home and Numpad 7 
Left and Numpad 4 
Up and Numpad 8 
Right and Numpad 6 
Down and Numpad 2 
Print Screen 

ins and Numpad 0 
Del and Numpad &bd. 
Scroll Lock 

Num Lock 

Shift + Enter and Numpad Enter 


Alt + Print Screen 
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VK_F1 * 
VK_F2 * 
VK_F3 * 
VK_F4 * 
VK_F5 * 
VK_F6 * 
VK_F7 * 
VK_F8 * 
VK_F9 * 
VK_F10 * 
VK_Fi1 * 
VK_F12 * 
VK_F13 
VK_F14 
VK_F15 
VK_F16 
VK_F17 
VK_F18 
VK_F19 
VK_F20 — 
VK_F21 
VK_F22 
VK_F23 
VK_F24 
VK_MENU * 


Notes: 


1. VKEYs marked with an asterisk (*) are generated irrespective of other shift states (Shift, 
Ctrl, Alt, and Alt Graf). 


2. VK_CAPSLOCK is not generated for any of the Ctrl shift states, for PC-DOS 
compatibility. 


3. Wherever possible, the VK_ name is derived from the legend on the key top of the 
101-key Enhanced PC keyboard. 
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Appendix I. Notices 


References in this publication to IBM products, programs, or services do not imply that IBM 
intends to make these available in all countries in which IBM operates. Any reference to an 
IBM product, program or service is not intended to state or imply that only IBM’s product, 
program, or service may be used. Any functionally equivalent product, program, or service 
that does not infringe any of IBM’s intellectual property rights or other legally protectable 
rights may be used instead of the IBM product, program, or service. Evaluation and 
verification of operation in conjunction with other products, programs, or services, except 
those expressly designated by IBM, are the user’s responsibility. 


IBM may have patents or pending patent applications covering subject matter in this 
document. The furnishing of this document does not give you any license to these patents. 
You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 
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Glossary 


This glossary defines many of the terms used in this 
book. It includes terms and definitions from the /BM 
Dictionary of Computing, as well as terms specific to 
the OS/2 operating system and the Presentation 
Manager. It is not a complete glossary for the entire 
OS/2 operating system; nor is it a complete 
dictionary of computer terms. 


Other primary sources for these definitions are: 


e The American National Standard Dictionary for 
Information Systems, ANSI X3.172-1990, 
copyrighted 1990 by the American National 
Standards Institute, 11 West 42nd Street, New 
York, New York 10036. These definitions are 
identified by the symbol (A) after the definition. 


e The Information Technology Vocabulary, 
developed by Subcommittee 1, Joint Technical 
Committee 1, of the International Organization 
for Standardization and the International 
Electrotechnical Commission (ISO/IEC 
JTC1/SC1). Definitions of published parts of this 
vocabulary are identified by the symbol (I) after 
the definition; definitions taken from draft 
international standards, committee drafts, and 
working papers being developed by ISO/IEC 
JTC1/SC1 are identified by the symbol (T) after 
the definition, indicating that final agreement has 
not yet been reached among the participating 
National Bodies of SC1. 
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Glossary Listing 


A 


accelerator. In SAA Common User Access 
architecture, a key or combination of keys that 
invokes an application-defined function. 


accelerator table. A table used to define which key 
strokes are treated as accelerators and the 
commands they are translated into. 


access mode. The manner in which an application 
gains access to a file it has opened. Examples of 
access modes are read-only, write-only, and 
read/write. 


access permission. All access rights that a user 
has regarding an object. (I) 


action. One of a set of defined tasks that a 
computer performs. Users request the application to 
perform an action in several ways, such as typing a 
command, pressing a function key, or selecting the 
action name from an action bar or menu. 


action bar. In SAA Common User Access 
architecture, the area at the top of a window that 
contains choices that give a user access to actions 
available in that window. 


action point. The current position on the screen at 
which the pointer is pointing. Contrast with hot spot 
and input focus. 


active program. A program currently running on 
the computer. An active program can be interactive 
(running and receiving input from the user) or 
noninteractive (running but not receiving input from 
the user). See also interactive program and 
noninteractive program. 


active window. The window with which the user is 
currently interacting. 


address space. (1) The range of addresses 
available to a program. (A) (2) The area of virtual 
storage available for a particular job. 


alphanumeric video output. Output to the logical 
video buffer when the video adapter is in text mode 
and the logical video buffer is addressed by an 

application as a rectangular array of character cells. 


American National Standard Code for Information 
Interchange. The standard code, using a coded 
character set consisting of 7-bit coded characters (8 
bits including parity check), that is used for 
information interchange among data processing 
systems, data communication systems, and 
associated equipment. The ASCII set consists of 
control characters and graphic characters. (A) 


Note: IBM has defined an extension to ASCII code 
(characters 128-255). 


anchor. A window procedure that handles 
Presentation Manager* message conversions 
between an icon procedure and an application. 


anchor block. An area of 
Presentation-Manager-internal resources to allocated 
process or thread that calls Winlnitialize. 


anchor point. A point in a window used by a 
program designer or by a window manager to 
position a subsequently appearing window. 


ANSI. American National Standards Institute. 
APA. All points addressable. 

API. Application programming interface. 
application. A collection of software components 
used to perform specific types of work ona 
computer; for example, a payroll application, an 


airline reservation application, a network application. 


application object. In SAA Advanced Common 
User Access architecture, a form that an application 


provides for a user; for example, a spreadsheet form. 


Contrast with user object. 


application programming interface (API). A 
functional interface supplied by the operating system 
or by a separately orderable licensed program that 
allows an application program written in a high-level 
language to use specific data or functions of the 
operating system or the licensed program. 
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application-modal. Pertaining to a message box or 
dialog box for which processing must be completed 
before further interaction with any other window 
owned by the same application may take place. 


area. In computer graphics, a filled shape such as a 
solid rectangle. 


ASCII. American National Standard Code for 
Information Interchange. 


ASCIIZ. A string of ASCII characters that is 
terminated with a byte containing the value 0. 


aspect ratio. In computer graphics, the 
width-to-height ratio of an area, symbol, or shape. 


asynchronous (ASYNC). (1) Pertaining to two or 
more processes that do not depend upon the 
occurrence of specific events such as common 
timing signals. (T) (2) Without regular time 
relationship; unexpected or unpredictable with 
respect to the execution of program instructions. 
See also synchronous. 


atom. A constant that represents a string. As soon 
as a string has been defined as an atom, the atom 
can be used in place of the string to save space. 
Strings are associated with their respective atoms in 
an atom table. See also integer atom. 


atom table. A table used to relate atoms with the 
strings that they represent. Also in the table is the 
mechanism by which the presence of a string can be 
checked. 


atomic operation. An operation that completes its 
work on an object before another operation can be 
performed on the same object. 


attribute. A characteristic or property that can be 
controlled, usually to obtain a required appearance; 
for example, the color of a line. See also graphics 
attributes and segment attributes. 


automatic link. In Information Presentation Facility 
(IPF), a link that begins a chain reaction at the 
primary window. When the user selects the primary 
window, an automatic link is activated to display 
secondary windows. 


AVIO. Advanced Video Input/Output. 


Bézier curve. (1) A mathematical technique of 
specifying smooth continous lines and surfaces, 
which require a starting point and a finishing point 
with several intermediate points that influence or 
control the path of the linking curve. Named after 
Dr. P. Bézier. (2) (D of C) In the AIX Graphics 
Library, a cubic spline approximation to a set of four 
control points that passes through the first and fourth 
control points and that has a continuous slope where 
two spline segments meet. Named after Dr. P. 
Bézier. 


background. (1) In multiprogramming, the 
conditions under which low-priority programs are 
executed. Contrast with foreground. (2) An active 
session that is not currently displayed on the screen. 


background color. The color in which the 
background of a graphic primitive is drawn. 


background mix. An attribute that determines how 
the background of a graphic primitive is combined 
with the existing color of the graphics presentation 
space. Contrast with mix. 


background program. In multiprogramming, a 
program that executes with a low priority. Contrast 
with foreground program. 


bit map. A representation in memory of the data 
displayed on an APA device, usually the screen. 


block. (1) A string of data elements recorded or 
transmitted as a unit. The elements may be 
characters, words, or logical records. (T) (2) To 
record data in a block. (3) A collection of contiguous 
records recorded as a unit. Blocks are separated by 
interblock gaps and each block may contain one or 
more records. (A) 


block device. A storage device that performs I/O 
operations on blocks of data called sectors. Data on 
block devices can be randomly accessed. Block — 
devices are designated by a drive letter (for example, 
C:). 


blocking mode. A condition set by an application 
that determines when its threads might block. For 
example, an application might set the Pipemode 

parameter for the DosCreateNPipe function so that 


its threads perform 1/O operations to the named pipe 
block when no data is available. 


border. A visual indication (for example, a 
separator line or a background color) of the 
boundaries of a window. 


boundary determination. An operation used to 
compute the size of the smallest rectangle that 
encloses a graphics object on the screen. 


breakpoint. (1) A point in a computer program 
where execution may be halted. A breakpoint is 
usually at the beginning of an instruction where halts, 
caused by external intervention, are convenient for 
resuming execution. (T) (2) A place in a program, 
specified by a command or a condition, where the 
system halts execution and gives control to the 
workstation user or to a specified program. 


broken pipe. When all of the handles that access 
one end of a pipe have been closed. 


bucket. One or more fields in which the result of an 
operation is kept. 


buffer. (1) A portion of storage used to hold input 
or output data temporarily. (2) To allocate and 
schedule the use of buffers. (A) 


button. A mechanism used to request or initiate an 
action. See also barre! buttons, bezel buttons, 
mouse button, push button, and radio button. 


byte pipe. Pipes that handle data as byte streams. 
All unnamed pipes are byte pipes. Named pipes can 
be byte pipes or message pipes. See byte stream. 


byte stream. Data that consists of an unbroken 
stream of bytes. 


C 


cache. A high-speed buffer storage that contains 
frequently accessed instructions and data; it is used 
to reduce access time. 


cached micro presentation space. A presentation 
space from a Presentation-Manager-owned store of 
micro presentation spaces. !t can be used for 
drawing to a window only, and must be returned to 
the store when the task is complete. 


CAD. Computer-Aided Design. 
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call. (1) The action of bringing a computer program, 
a routine, or a subroutine into effect, usually by 
specifying the entry conditions and jumping to an 
entry point. (I) (A) (2) To transfer control to a 
procedure, program, routine, or subroutine. 


calling sequence. A sequence of instructions 
together with any associated data necessary to 
execute a call. (T) 


Cancel. An action that removes the current window 
or menu without processing it, and returns the 
previous window. 


cascaded menu. In the OS/2 operating system, a 
menu that appears when the arrow to the right of a 
cascading choice is selected. It contains a set of 
choices that are related to the cascading choice. 
Cascaded menus are used to reduce the length of a 
menu. See also cascading choice. 


cascading choice. In SAA Common User Access 
architecture, a choice in a menu that, when selected, 
produces a cascaded menu containing other choices. 
An arrow (->) appears to the right of the cascading 
choice. 


CASE statement. In PM programming, provides the 
body of a window procedure. There is usually one 
CASE statement for each message type supported 

~ by an application. 


CGA. Color graphics adapter. 


chained list. A list in which the data elements may 
be dispersed but in which each data element 
contains information for locating the 

next. (T) Synonymous with /inked list. 


character. A letter, digit, or other symbol. 


character box. In computer graphics, the boundary 
that defines, in world coordinates, the horizontal and 
vertical space occupied by a single character from a 
character set. See also character mode. Contrast 
with character cell. 


character cell. The physical, rectangular space in 
which any single character is displayed on a screen 
or printer device. Position is addressed by row and 
column coordinates. Contrast with character box. 


character code. The means of addressing a 


character in a character set, sometimes called code 
point. 
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character device. A device that performs I/O 
operations on one character at a time. Because 
character devices view data as a stream of bytes, 
character-device data cannot be randomly accessed. 
Character devices include the keyboard, mouse, and 
printer, and are referred to by name. 


character mode. A mode that, in conjunction with 
the font type, determines the extent to which 
graphics characters are affected by the character 
box, shear, and angle attributes. 


character set. (1) An ordered set of unique 
representations called characters; for example, the 
26 letters of English alphabet, Boolean 0 and 1, the 
set of symbols in the Morse code, and the 128 ASCII 
characters. (A) (2) All the valid characters for a 
programming language or for a computer system. 

(3) A group of characters used for a specific reason; 
for example, the set of characters a printer can print. 


check box. In SAA Advanced Common User 
Access architecture, a square box with associated 
text that represents a choice. When a user selects a 
choice, an X appears in the check box to indicate 
that the choice is in effect. The user can clear the 
check box by selecting the choice again. Contrast 
with radio button. 


check mark. (1) (D of C) In SAA Advanced 
Common User Access architecture, a (V) symbol that 
shows that a choice is currently in effect. (2) The 
symbol that is used to indicate a selected item ona 
pull-down menu. 


child process. In the OS/2 operating system, a 
process started by another process, which is called 
the parent process. Contrast with parent process. 


child window. A window that appears within the 
border of its parent window (either a primary window 
or another child window). When the parent window 
is resized, moved, or destroyed, the child window 
also is resized, moved, or destroyed; however, the 
child window can be moved or resized independently 
from the parent window, within the boundaries of the 
parent window. Contrast with parent window. 


choice. (1) An option that can be selected. The 
choice can be presented as text, as a symbol 
(number or letter), or as an icon (a pictorial symbol). 
(2) (D of C) in SAA Common User Access 
architecture, an item that a user can select. 


chord. (1) To press more than one button ona 
pointing device while the pointer is within the limits 
that the user has specified for the operating 
environment. (2) (D of C) In graphics, a short line 
segment whose end points lie on a circle. Chords 
are a means for producing a circular image from 
straight lines. The higher the number of chords per 
circle, the smoother the circular image. 


class. In object-oriented design or programming, a 
group of objects that share a common definition and 
that therefore share common properties, operations, 
and behavior. Members of the group are called 
instances of the class. 


class method. In System Object Model, an action 
that can be performed on a class object. 
Synonymous with factory method. 


class object. In System Object Model, the run-time 
implementation of a class. 


class style. The set of properties that apply to 
every window in a window class. 


client. (1) A functional unit that receives shared 
services from a server. (T) (2) Auser, asina 
client process that uses a named pipe or queue that 
is created and owned by a server process. 


client area. The part of the window, inside the 
border, that is below the menu bar. It is the user’s 
work space, where a user types information and 
selects choices from selection fields. In primary 
windows, it is where an application programmer 
presents the objects that a user works on. 


client program. An application that creates and 
manipulates instances of classes. 


client window. The window in which the application 
displays output and receives input. This window is 
located inside the frame window, under the window 
title bar and any menu bar, and within any scroll 
bars. 


clip limits. The area of the paper that can be 
reached by a printer or plotter. 


clipboard. In SAA Common User Access 
architecture, an area of computer memory, or 
storage, that temporarily holds data. Data in the 
clipboard is available to other applications. 


clipping. In computer graphics, removing those 
parts of a display image that lie outside a given 
boundary. (I) (A) 


clipping area. The area in which the window can 
paint. 


clipping path. A clipping boundary in 
world-coordinate space. 


clock tick. The minimum unit of time that the 
system tracks. If the system timer currently counts 
at a rate of X Hz, the system tracks the time every 
1/X of a second. Also known as time tick. 


CLOCK$. Character-device name reserved for the 
system clock. 


code page. An assignment of graphic characters 
and control-function meanings to all code points. 


code point. (1) Synonym for character code. (2) 
(D of C) A 1-byte code representing one of 256 
potential characters. 


code segment. An executable section of 
programming code within a load module. 


color dithering. See dithering. 


color graphics adapter (CGA). An adapter that 
simultaneously provides four colors and is supported 
by all IBM Personal Computer and Personal 
System/2 models. 


command. The name and parameters associated 
with an action that a program can perform. 


command area. An area composed of a command 
field prompt and a command entry field. 


command entry field. An entry field in which users 
type commands. 


command line. On a display screen, a display line, 
sometimes at the bottom of the screen, in which only 
commands can be entered. 


command mode. A state of a system or device in 


‘which the user can enter commands. 


command prompt. A field prompt showing the 
location of the command entry field in a panel. 


Common Programming Interface (CPi). 
Definitions of those application development 
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languages and services that have, or are intended to 
have, implementations on and a high degree of 
commonality across the SAA environments. One of 
the three SAA architectural areas. See also 
Common User Access. architecture. 


Common User Access (CUA) architecture. 
Guidelines for the dialog between a human and a 
workstation or terminal. One of the three SAA 
architectural areas. See also Common Programming 
Interface. 


compile. To translate a program written in a 
higher-level programming language into a machine 
language program. 


composite window. A window composed of other 
windows (such as a frame window, frame-contro! 
windows, and a client window) that are kept together 
as a unit and that interact with each other. 


computer-aided design (CAD). The use of a 
computer to design or change a product, tool, or 
machine, such as using a computer for drafting or 
illustrating. 


COM1, COM2, COM3. Character-device names 
reserved for serial ports 1 through 3. 


CON. Character-device name reserved for the 
console keyboard and screen. 


container. In SAA Common User Access 
architecture, an object that holds other objects. A 
folder is an example of a container object. See also 
folder and object. 


contextual help. In SAA Common User Access 
Architecture, help that gives specific information 
about the item the cursor is on. The help is 
contextual because it provides information about a 
specific item as it is currently being used. Contrast 
with extended help. 


contiguous. Touching or joining at a common edge 
or boundary, for example, an unbroken consecutive 
series of storage locations. 


control. In SAA Advanced Common User Access 
architecture, a component of the user interface that 
allows a user to select choices or type information; 
for example, a check box, an entry field, a radio 
button. 
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control area. A storage area used by a computer 
program to hold control information. (!) (A) 


Control Panel. In the Presentation Manager, a 
program used to set up user preferences that act 
globally across the system. 


Control Program. (1) The basic functions of the 
operating system, including DOS emulation and the 
support for keyboard, mouse, and video input/output. 
(2) A computer program designed to schedule and to 
supervise the execution of programs of a computer 
system. (I) (A) 


control window. A window that is used as part of a 
composite window to perform simple input and 
output tasks. Radio buttons and check boxes are 
examples. 


control word. An instruction within a document that 
identifies its parts or indicates how to format the 
document. 


coordinate space. A two-dimensional set of points 
used to generate output on a video display of printer. 


Copy. A choice that places onto the clipboard, a 
copy of what the user has selected. See also Cut 
and Paste. 


correlation. The action of determining which 
element or object within a picture is at a given 
position on the display. This follows a pick 
operation. 


coverpage window. A window in which the 
application's help information is displayed. 


CPi. Common Programming Interface. 


critical extended attribute. An extended attribute 
that is necessary for the correct operation of the 
system or a particular application. 


critical section. (1) In programming languages, a 
part of an asynchronous procedure that cannot be 
executed simultaneously with a certain part of 
another asynchronous procedure. (|) 


Note: Part of the other asynchronous procedure 
also is a critical section. (2) A section of code that is 
not reentrant; that is, code that can be executed by 
only one thread at a time. 


CUA architecture. Common User Access 
architecture. 


current position. In computer graphics, the 
position, in user coordinates, that becomes the 
starting point for the next graphics routine, if that 
routine does not explicitly specify a starting point. 


cursor. A symbol displayed on the screen and 
associated with an input device. The cursor 
indicates where input from the device will be placed. 
Types of cursors include text cursors, graphics 
cursors, and selection cursors. Contrast with pointer 
and input focus. 


Cut. In SAA Common User Access architecture, a 
choice that removes a selected object, or a part of 

an object, to the clipboard, usually compressing the 
space it occupied in a window. See also Copy and 
Paste. 


D 


daisy chain. A method of device interconnection for 
determining interrupt priority by connecting the 
interrupt sources serially. 


data segment. A nonexecutable section of a 
program module; that is, a section of a program that 
contains data definitions. 


data structure. The syntactic structure of symbolic 
expressions and their storage-allocation 
characteristics. (T) 


data transfer. The movement of data from one 
object to another by way of the clipboard or by direct 
manipulation. 


DBCS. Double-byte character set. 
DDE. Dynamic data exchange. 


deadlock. (1) Unresolved contention for the use of 
a resource. (2) An error condition in which 
processing cannot continue because each of two 
elements of the process is waiting for an action by, 
or a response from, the other. (3) An impasse that 
occurs when multiple processes are waiting for the 
availability of a resource that will not become 
available because it is being held by another process 
that is in a similar wait state. 


debug. To detect, diagnose, and eliminate errors in 
programs. (T) 


decipoint. In printing, one tenth of a point. There 
are 72 points in an inch. 


default procedure. A function provided by the 
Presentation Manager Interface that may be used to 
process standard messages from dialogs or 
windows. 


default value. A value assumed when no value has 
been specified. Synonymous with assumed value. 
For example, in the graphics programming interface, 
the default line-type is ‘solid’. 


definition list. A type of list that pairs a term and 
its description. 


delta. An application-defined threshold, or number 
of container items, from either end of the list. 


descendant. See child process. 


descriptive text. Text used in addition to a field 
prompt to give more information about a field. 


Deselect all. A choice that cancels the selection of 
all of the objects that have been selected in that 
window. 


Desktop Manager. In the Presentation Manager, a 
window that displays a list of groups of programs, 
each of which can be started or stopped. 


desktop window. The window, corresponding to 
the physical device, against which all other types of 
windows are established. 


detached process. A background process that 
runs independent of the parent process. 


detent. A point on a slider that represents an exact 
value to which a user can move the slider arm. 


device context. A logical description of a data 
destination such as memory, metafile, display, 
printer, or plotter. See also direct device context, 
information device context, memory device context, 
metafile device context, queued device context, and 
screen device context. 


device driver. A file that contains the code needed 
to attach and use a device such as a display, printer, 
or plotter. 


device space. (1) Coordinate space in which — 
graphics are assembled after all GP! transformations 


have been applied. Device space is defined in 
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device-specific units. (2) (D of C) In computer 
graphics, a space defined by the complete set of 
addressable points of a display device. (A) 


dialog. The interchange of information between a 
computer and its user through a sequence of 
requests by the user and the presentation of 
responses by the computer. 


dialog box. In SAA Advanced Common User 
Access architecture, a movable window, fixed in size, 
containing controls that a user uses to provide 
information required by an application so that it can 
continue to process a user request. See also 
message box, primary window, secondary window. 
Also known as a pop-up window. 


Dialog Box Editor. A WYS/WYG editor that 
creates dialog boxes for communicating with the 
application user. 


dialog item. A component (for example, a menu or 
a button) of a dialog box. Dialog items are also used 
when creating dialog templates. 


dialog procedure. A dialog window that is 
controlled by a window procedure. It is responsible 
for responding to all messages sent to the dialog 
window. 


dialog tag language. A markup language used by 
the DTL compiler to create dialog objects. 


dialog template. The definition of a dialog box, 
which contains details of its position, appearance, 
and window ID, and the window ID of each of its 
child windows. 


direct device context. A logical description of a 
data destination that is a device other than the 
screen (for example, a printer or plotter), and where 
the output is not to go through the spooler. Its 
purpose is to satisfy queries. See also device 
context. 


direct manipulation. The action of using the 
mouse to move objects around the screen. For 
example, moving files and directories around in the 
Workplace Shell. 


direct memory access (DMA). A technique for 
moving data directly between main storage and 
peripheral equipment without requiring processing of 
the data by the processing unit.(T) 
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directory. A type of file containing the names and 
controlling information for other files or other 
directories. 


display point. Synonym for pel. 
dithering. (1) The process used in color displays 


whereby every other pel is set to one color, and the 
intermediate pels are set to another. Together they 


' produce the effect of a third color at normal viewing 


distances. This process can only be used on solid 
areas of color; it does not work, for example, on 
narrow lines. (2) (D of C ) In computer graphics, a 
technique of interleaving dark and light pixels so that 
the resulting image looks smoothly shaded when 
viewed from a distance. 


DMA. Direct memory access. 


DOS Protect Mode Interface (DPMI). An interface 
between protect mode and real mode programs. 


double-byte character set (DBCS). A set of 
characters in which each character is represented by 
two bytes. Languages such-as Japanese, Chinese, 
and Korean, which contain more characters than can 
be represented by 256 code points, require 
double-byte character sets. Since each character 
requires two bytes, the entering, displaying, and 
printing of DBCS characters requires hardware and 
software that can support DBCS. 


doubleword. A contiguous sequence of bits or 
characters that comprises two computer words and 
is capable of being addressed as a unit. (A) 


DPMI. DOS Protect Mode Interface. 


drag. In SAA Common User Access, to use a 
pointing device to move an object; for example, 
clicking on a window border, and dragging it to make 
the window larger. 


dragging. (1) In computer graphics, moving an 
object on the display screen as if it were attached to 
the pointer. (2) (D of C) In computer graphics, 
moving one or more segments on a display surface 
by translating. (I) (A) 


drawing chain. See segment chain. 
drop. To fix the position of an object that is being 


dragged, by releasing the select button of the 
pointing device. 


drop. To fix the position of an object that is being 
dragged, by releasing the select button of the 
pointing device. See also drag. 


DTL. Dialog tag language. 


dual-boot function. A feature of the OS/2 
operating system that allows the user to start DOS 
from within the operating system, or an OS/2 session 
from within DOS. 


duplex. Pertaining to communication in which data 
can be sent and received at the same time. 
Synonymous with full duplex. 


dynamic data exchange (DDE). A message 
protocol used to communicate between applications 
that share data. The protocol uses shared memory 
as the means of exchanging data between 
applications. 


dynamic data formatting. A formatting procedure 
that enables you to incorporate text, bit maps or 
metafiles in an IPF window at execution time. 


dynamic link library. A collection of executable 
programming code and data that is bound to an 
application at load time or run time, rather than 
during linking. The programming code and data ina 
dynamic link library can be shared by several 
applications simultaneously. 


dynamic linking. The process of resolving external 
references in a program module at load time or run 
time rather than during linking. 


dynamic segments. Graphics segments drawn in 
exclusive-OR mix mode so that they can be moved 
from one screen position to another without affecting 
the rest of the displayed picture. 


dynamic storage. (1) A device that stores data ina 
manner that permits the data to move or vary with 
time such that the specified data is not always 
available for recovery. (A) (2) A storage in which 
the ceils require repetitive application of control 
signals in order to retain stored data. Such repetitive 
application of the control signals is called a refresh 
operation. A dynamic storage may use static 
addressing or sensing circuits. (A) (3) See also 
static storage. 


dynamic time slicing. Varies the size of the time 
slice depending on system load.and paging activity. 


dynamic-link module. A module that is linked at 
load time or run time. 


E 


EBCDIC. Extended binary-coded decimal 
interchange code. A coded character set consisting 
of 8-bit coded characters (9 bits including parity 
check), used for information interchange among data 
processing systems, data communications systems, 
and associated equipment. 


edge-triggered. Pertaining to an event semaphore 
that is posted then reset before a waiting thread gets 
a chance to run. The semaphore is considered to be 
posted for the rest of that thread’s waiting period; the 
thread does not have to wait for the semaphore to 
be posted again. 


EGA. Extended graphics adapter. 


element. An entry in a graphics segment that 
comprises one or more graphics orders and that is 
addressed by the element pointer. 


EMS. Expanded Memory Specification. 


encapsulation. Hiding an object’s implementation, 
that is, its private, internal data and methods. 

Private variables and methods are accessible only to 
the object that contains them. 


entry field. In SAA Common User Access 
architecture, an area where a user types information. 
Its boundaries are usually indicated. See also 
selection field. 


entry panel. A defined panel type containing one or 
more entry fields and protected information such as 
headings, prompts, and explanatory text. 


entry-field control. The component of a user 
interface that provides the means by which the 
application receives data entered by the user in an 
entry field. When it has the input focus, the entry 
field displays a flashing pointer at the position where 
the next typed character will go. 


environment segment. The list of environment 
variables and their values for a process. 


environment strings. ASCII text strings that define 
the value of environment variables. 
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environment variables. Variables that describe the 
execution environment of a process. These 
variables are named by the operating system or by 
the application. Environment variables named by the 
operating system are PATH, DPATH, INCLUDE, 
INIT, LIB, PROMPT, and TEMP. The values of 
environment variables are defined by the user in the 
CONFIG.SYS file, or by using the SET command at 
the OS/2 command prompt. 


error message. An indication that an error has 
been detected. (A) 


event semaphore. A semaphore that enables a 
thread to signal a waiting thread or threads that an 
event has occurred or that a task has been 
completed. The waiting threads can then perform an 
action that is dependent on the completion of the 
signaled event. 


exception. An abnormal condition such as an I/O 
error encountered in processing a data set or a file. 


exclusive system semaphore. A system 
semaphore that can be modified only by threads 
within the same process. 


executable file. (1) A file that contains programs or 
commands that perform operations or actions to be 
taken. (2) A collection of related data records that 
execute programs. 


exit. To execute an instruction within a portion of a 
computer program in order to terminate the 
execution of that portion. Such portions of computer 
programs include loops, subroutines, modules, and 
soon. (T) Repeated exit requests return the user 
to the point from which all functions provided to the 
system are accessible. Contrast with cancel. 


expanded memory specification (EMS). Enables 
DOS applications to access memory above the 1MB 
real mode addressing limit. 


extended attribute. An additional piece of 
information about a file object, such as its data 
format or category. It consists of a name and a 
value. A file object may have more than one 
extended attribute associated with it. 


extended help. In SAA Common User Access 
architecture, a help action that provides information 
about the contents of the application window from 
which a user requested help. Contrast with 
contextual help. 
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extended-choice selection. A mode that allows 
the user to select more than one item from a 
window. Not all windows allow extended choice 
selection. Contrast with multiple-choice selection. 


extent. Continuous space on a disk or diskette that 
is occupied by or reserved for a particular data set, 
data space, or file. 


external link. In Information Presentation Facility, a 
link that connects external online document files. 


F 


family-mode application. An application program 
that can run in the OS/2 environment and in the 
DOS environment; however, it cannot take 
advantage of many of the OS/2-mode facilities, such 
as multitasking, interprocess communication, and 
dynamic linking. 


FAT. File allocation table. 
FEA. Full extended attribute. 


field-level help. Information specific to the field on 
which the cursor is positioned. This help function is 
“contextual” because it provides information about a 
specific item as it is currently used; the information is 
dependent upon the context within the work session. 


FIFO. First-in-first-out. (A) 


file. A named set of records stored or processed as 
a unit. (T) 


file allocation table (FAT). In IBM personal 
computers, a table used by the operating system to 
allocate space on a disk for a file, and to locate and 
chain together parts of the file that may be scattered 
on different sectors so that the file can be used in a 
random or sequential manner. 


file attribute. Any of the attributes that describe the 
characteristics of a file. 


File Manager. in the Presentation Manager, a 
program that displays directories and files, and 
allows various actions on them. 


file specification. The full identifier for.a file, which 
includes its drive designation, path, file name, and 
extension. 


file system. The combination of software and 
hardware that supports storing information on a 
storage device. 


file system driver (FSD). A program that manages 
file I\O and controls the format of information on the 
storage media. 


fillet. A curve that is tangential to the end points of 
two adjoining lines. See also polyfillet. 


filtering. An application process that changes the 
order of data in a queue. 


first-in-first-out (FIFO). A queuing technique in 
which the next item to be retrieved is the item that 
has been in the queue for the longest time. (A) 


flag. (1) An indicator or parameter that shows the 
setting of a switch. (2) A character that signals the 
occurrence of some condition, such as the end of a 
word. (A) (3) (D of C) A characteristic of a file or 
directory that enables it to be used in certain ways. 
See also archive flag, hidden flag, and read-only 
flag. 


focus. See input focus. 
folder. A container used to organize objects. 


font. A particular size and style of typeface that 
contains definitions of character sets, marker sets, 
and pattern sets. 


Font Editor. A utility program provided with the IBM 
Developers Toolkit that enables the design and 
creation of new fonts. 


foreground program. (1) The program with which 
the user is currently interacting. Also known as 
interactive program. Contrast with background 

_ program. (2) (D of C) In multiprogramming, a 
high-priority program. 


frame. The part of a window that can contain 
several different visual elements specified by the 
application, but drawn and controlled by the 
Presentation Manager. The frame encloses the 
client area. 


frame styles. Standard window layouts provided by 
the Presentation Manager. 


FSD. File system driver. 


full-duplex. Synonym for duplex. 


full-screen application. An application that has 
complete control of the screen. 


function. (1) In a programming language, a block, 
with or without formal parameters, whose execution 
is invoked by means of acall. (2) A set of related 
control statements that cause one or more programs 
to be performed. 


function key. A key that causes a specified 
sequence of operations to be performed when it is 
pressed, for example, F1 and Alt-K. 


function key area. The area at the bottom of a 
window that contains function key assignments such 
as F1=Help. 


G 


GDT. Global Descriptor Table. 


general protection fault. An exception condition 
that occurs when a process attempts to use storage 
or a module that has some level of protection 
assigned to it, such as I/O privilege level. See also 
IOPL code segment. 


Global Descriptor Table (GDT). A table that 
defines code and data segments available to all 
tasks in an application. 


global dynamic-link module. A dynamic-link 
module that can be shared by all processes in the 
system that refer to the module name. 


global file-name character. Either a question mark 
(?) or an asterisk (*) used as a variable in a file 
name or file name extension when referring to a 
particular file or group of files. 


glyph. A graphic symbol whose appearance 
conveys information. 


GPI. Graphics programming interface. 


graphic primitive. In computer graphics, a basic 
element, such as an arc or a line, that is not made 
up of smaller parts and that is used to create 
diagrams and pictures. See also graphics segment. 


graphics. (1) A picture defined in terms of graphic 
primitives and graphics attributes. (2) (D of C) The 
making of charts and pictures. (3) Pertaining to 
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charts, tables, and their creation. (4) See computer 
graphics, coordinate graphics, fixed-image graphics, 
interactive graphics, passive graphics, raster 
graphics. 


graphics attributes. Attributes that apply to graphic 
primitives. Examples are color, line type, and 
shading-pattern definition. See also segment 
attributes. 


graphics field. The clipping boundary that defines 
the visibie part of the presentation-page contents. 


graphics mode. One of several states of a display. 
The mode determines the resolution and color 
content of the screen. 


graphics model space. The conceptual coordinate 
space in which a picture is constructed after any 
model transforms have been applied. Also known as 
model space. 


Graphics programming interface. The formally 
defined programming language that is between an 
IBM graphics program and the user of the program. 


graphics segment. A sequence of related graphic 
primitives and graphics attributes. See also graphic 
primitive. 


graying. The indication that a choice ona 
pull-down is unavailable. 


group. A collection of logically connected controls. 
For example, the buttons controlling paper size for a 
printer could be called a group. See also program 
group. 


H 


handle. (1) An identifier that represents an object, 
such as a device or window, to the Presentation 
Interface. (2) (D of C) In the Advanced DOS and 
OS/2 operating systems, a binary value created by 
the system that identifies a drive, directory, and file 
so that the file can be found and opened. 


hard error. An error condition on a network that 

requires either that the system be reconfigured or 

that the source of the error be removed before the 
system can resume reliable operation. 


header. (1) System-defined control information that 
precedes user data. (2) The portion of a message 
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that contains control information for the message, 
such as one or more destination fields, name of the 
originating station, input sequence number, character 
string indicating the type of message, and priority 
level for the message. 


heading tags. A document element that enables 
information to be displayed in windows, and that 
controls entries in the contents window controls 
placement of push buttons in a window, and defines 
the shape and size of windows. 


heap. An area of free storage available for dynamic 
allocation by an application. Its size varies according 
to the storage requirements of the application. 


help function. (1) A function that provides 
information about a specific field, an application 
panel, or information about the help facility. (2) (D of 
C) One or more display images that describe how to 
use application software or how to do a system 
operation. 


Help index. In SAA Common User Access 
architecture, a help action that provides an index of 
the help information available for an application. 


help panel. A panel with information to assist users 
that is displayed in response to a help request from 
the user. . 


help window. A Common-User-Access-defined 
secondary window that displays information when the 
user requests help. 


hidden file. An operating system file that is not 
displayed by a directory listing. 


hide button. In the OS/2 operating system, a small, 
square button located in the right-hand corner of the 
title bar of a window that, when selected, removes 
from the screen all the windows associated with that 
window. Contrast with maximize button. See also 
restore button. 


hierarchical inheritance. The relationship between 
parent and child classes. An object that is lower in 
the inheritance hierarchy than another object, inherits 
all the characteristics and behaviors of the objects 
above it in the hierarchy. 


hierarchy. A tree of segments beginning with the 
root segment and proceeding downward to 
dependent segment types. 


high-performance file system (HPFS). In the 
OS/2 operating system, an installable file system that 
uses high-speed buffer storage, known as a cache, 
to provide fast access to large disk volumes. The 
file system also supports the coexistence of multiple, 
active file systems on a single personal computer, 
with the capability of multiple and different storage 
devices. File names used with the HPFS can have 
as many as 254 characters. 


hit testing. The means of identifying which window 
is associated with which input device event. 


hook. A point in a system-defined function where 
an application can supply additional code that the 
system processes as though it were part of the 
function. 


hook chain. A sequence of hook procedures that 
are “chained” together so that each event is passed, 
in turn, to each procedure in the chain. 


hot spot. The part of the pointer that must touch an 
object before it can be selected. This is usually the 
tip of the pointer. Contrast with action point. 


HPFS. high-performance file system. 


hypergraphic link. A connection between one 
piece of information and another through the use of 
graphics. 


hypertext. A way of presenting information online 
with connections between one piece of information 
and another, called hypertext links. See also 
hypertext link. 


hypertext link. A connection between one piece of 
information and another. 


1/0 operation. An input operation to, or output 
operation from a device attached to a computer. 


I-beam pointer. A pointer that indicates an area, 
such as an entry field in which text can be edited. 


icon. In SAA Advanced Common User Access 
architecture, a graphical representation of an object, 
consisting of an image, image background, and a 
label. Icons can represent items (such as a 
document file) that the user wants to work on, and 
actions that the user wants to perform. In the 


Presentation Manager, icons are used for data 
objects, system actions, and minimized programs. 


icon area. In the Presentation Manager, the area at 
the bottom of the screen that is normally used to 
display the icons for minimized programs. 


icon Editor. The Presentation Manager-provided 


tool for creating icons. 


image font. A set of symbols, each of which is 
described in a rectangular array of pels. Some of 
the pels in the array are set to produce the image of 
one of the symbols. Contrast with outline font. 


indirect manipulation. Interaction with an object 
through choices and controls. 


information device context. A logical description 
of a data destination other than the screen (for 
example, a printer or plotter), but where no output 
will occur. Its purpose is to satisfy queries. See 
also device context. 


information panel. A defined panel type 
characterized by a body containing only protected 
information. 


Information Presentation Facility (IPF). A facility 
provided by the OS/2 operating system, by which 
application developers can produce online 
documentation and context-sensitive online help 
panels for their applications. 


input focus. (1) The area of a window where user 
interaction is possible using an input device, such as 
a mouse or the keyboard. (2) The position in the 
active window where a user’s normal interaction with 
the keyboard will appear. 


input router. An internal OS/2 process that 
removes messages from the system queue. 


input/output control. A device-specific command 
that requests.a function of a device driver. 


installable file system (IFS). A file system in which 
software is installed when the operating system is 
started. 


instance. A single occurrence of an object class 
that has a particular behavior. 


instruction pointer. In system/38, a pointer that 
provides addressability for a machine interface 
instruction in a program. 
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integer atom. An atom that represents a predefined 
system constant and carries no storage overhead. 
For example, names of window classes provided by 
Presentation Manager are expressed as integer 
atoms. ° 


interactive graphics. Graphics that can be moved 
or manipulated by a user at a terminal. 


interactive program. (1) A program that is running 
(active) and is ready to receive (or is receiving) input 
from a user. (2) A running program that can receive 
input from the keyboard or another input device. 
Compare with active program and contrast with 
noninteractive program. 


Also known as a foreground program. 


interchange file. A file containing data that can be 
sent from one Presentation Manager interface 
application to another. 


interpreter. A program that translates and executes 
each instruction of a high-level programming 
language before it translates and executes. 


interprocess communication (IPC). In the OS/2 
operating system, the exchange of information 
between processes or threads through semaphores, 
pipes, queues, and shared memory. 


interval timer. (1) A timer that provides program 
interruptions on a program-controlled basis. (2) An 
electronic counter that counts intervals of time under 
program control. 


1OCtl. input/output control. 

IOPL. input/output privilege level. 

IOPL. code segment. An IOPL executable section 
of programming code that enables an application to 
directly manipulate hardware interrupts and ports 
without replacing the device driver. See also 
privilege level. 

IPC. Interprocess communication. 

IPF. Information Presentation Facility. 

IPF compiler. A text compiler that interpret tags in 


a source file and converts the information into the 
specified format. 
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IPF tag language. A markup language that 
provides the instructions for displaying online 
information. 


item. A data object that can be passed in a DDE 
transaction. 


J 


journal. A special-purpose file that is used to 
record changes made in the system. 


K 


Kanji. A graphic character set used in Japanese 
ideographic alphabets. 


KBD$. Character-device name reserved for the 
keyboard. 


kernel. The part of an operating system that 
performs basic functions, such as allocating 
hardware resources. 


kerning. The design of graphics characters so that 
their character boxes overlap. Used to space text 
proportionally. 


keyboard accelerator. A keystroke that generates 
a command message for an application. 


keyboard augmentation. A function that enables a 
user to press a keyboard key while pressing a 
mouse button. 


keyboard focus. A temporary attribute of a 
window. The window that has a keyboard focus 
receives all keyboard input until the focus changes to 
a different window. 


Keys help. In SAA Common User Access 


architecture, a help action that provides a listing of 
the application keys and their assigned functions. 


L 


label. In a graphics segment, an identifier of one or 
more elements that is used when editing the 
segment. 


LAN. local area network. 


language support procedure. A function provided 
by the Presentation Manager Interface for 
applications that do not, or cannot (as in the case of 
COBOL and FORTRAN programs), provide their own 
dialog or window procedures. 


lazy drag. See pickup and drop. 
lazy drag set. See pickup set. 


LDT. In the OS/2 operating system, Local 
Descriptor Table. 


LIFO stack. A stack from which data is retrieved in 
last-in, first-out order. 


linear address. A unique value that identifies the 
memory object. 


linked list. Synonym for chained list. 


list box. In SAA Advanced Common User Access 
architecture, a control that contains scrollable 
choices from which a user can select one choice. 


Note: In CUA architecture, this is a programmer 
term. The end user term is selection list. 


list button. A button labeled with an underlined 
down-arrow that presents a list of valid objects or 
choices that can be selected for that field. 


list panel. A defined panel type that displays a list 
of items from which users can select one or more 
choices and then specify one or more actions to 
work on those choices. 


load time. The point in time at which a program 
module is loaded into main storage for execution. 


load-on-call. A function of a linkage editor that 
allows selected segments of the module to be disk 
resident while other segments are executing. Disk 
resident segments are loaded for execution and 
given control when any entry point that they contain 
is called. 


local area network (LAN). (1) A computer network 
located on a user’s premises within a limited 
geographical area. Communication within a local 
area network is not subject to external regulations; 
however, communication across the LAN boundary 
may be subject to some form of regulation. (T) 


Note: ALAN does not use store and forward 
techniques. (2) A network inwhich a set of devices 
are connected to one another for communication and 
that can be connected to a larger network. 


Local Descriptor Table (LDT). Defines code and 
data segments specific to a single task. 


lock. A serialization mechanism by means of which 
a resource is restricted for use by the holder of the 
lock. 


logical storage device. A device that the user can 
map to a physical (actual) device. 


LPT1, LPT2, LPT3. Character-device names 
reserved for parallel printers 1 through 3. 


main window. The window that is positioned 
relative to the desktop window. 


manipulation button. The button on a pointing 
device a user presses to directly manipulate an 
object. 


map. (1) A set of values having a defined 
correspondence with the quantities or values of 
another set. (I) (A) (2) To establish a set of 
values having a defined correspondence with the 
quantities or values of another set. (f) 


marker box. In computer graphics, the boundary 
that defines, in world coordinates, the horizontal and 
vertical space occupied by a single marker from a 
marker set. ; 


marker symbol. A symbol centered on a point. 
Graphs and charts can use marker symbols to 
indicate the plotted points. 


marquee box. The rectangle that appears during a 
selection technique in which a user selects objects 
by drawing a box around them with a pointing 
device. 


Master Help Index. In the OS/2 operating system, 
an alphabetic list of help topics related to using the 
operating system. 


maximize. To enlarge a window to its largest 
possible size. 
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media window. The part of the physical device 
(display, printer, or plotter) on which a picture is 
presented. 


memory block. Part memory within a heap. 


memory device context. A logical description of a 
data destination that is a memory bit map. See also 
device context. 


memory management. A feature of the operating 
system for allocating, sharing, and freeing main 
storage. 


memory object. Logical unit of memory requested 
by an application, which forms the granular unit of 
memory manipulation from the application viewpoint. 


menu. In SAA Advanced Common User Access 
architecture, an extension of the menu bar that 
displays a list of choices available for a selected 
choice in the menu bar. After a user selects a 
choice in menu bar, the corresponding menu 
appears. Additional pop-up windows can appear 
from menu choices. 


menu bar. In SAA Advanced Common User 
Access architecture, the area near the top of a 
window, below the title bar and above the rest of the 
window, that contains choices that provide access to 
other menus. 


menu button. The button on a pointing device that 
a user presses to view a pop-up menu associated 
with an object. 


message. (1) In the Presentation Manager, a 
packet of data used for communication between the 
Presentation Manager interface and Presentation 
Manager applications (2) In a user interface, 
information not requested by users but presented to 
users by the computer in response to a user action 
or internal process. 


message box. (1) A dialog window predefined by 
the system and used as a simple interface for 
applications, without the necessity of creating 
dialog-template resources or dialog procedures. (2) 
(D of C) In SAA Advanced Common User Access 
architecture, a type of window that shows messages 
to users. See also dialog box, primary window, 
secondary window. 
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message filter. The means of selecting which 
messages from a specific window will be handled by 
the application. 


message queue. A sequenced collection of 
messages to be read by the application. 


message stream mode. A method of operation in 
which data is treated as a stream of messages. 
Contrast with byte stream. 


metacharacter. See global file-name character. 


metaclass. The conjunction of an object and its 
class information; that is, the information pertaining 
to the class as a whole, rather than to a single 
instance of the class. Each class is itself an object, 
which is an instance of the metaclass. 


metafile. A file containing a series of attributes that 
set color, shape and size, usually of a picture or a 
drawing. Using a program that can interpret these 
attributes, a user can view the assembled image. . 


metafile device context. A logical description of a 
data destination that is a metafile, which is used for 
graphics interchange. See also device context. 


metalanguage. A language used to specify another 
language. For example, data types can be 
described using a metalanguage so as to make the 
descriptions independent of any one computer 
language. 


mickey. A unit of measurement for physical mouse 
motion whose value depends on the mouse device 
driver currently loaded. 


micro presentation space. A graphics presentation 
space in which a restricted set of the GPI function 
calls is available. 


minimize. To remove from the screen all windows 
associated with an application and replace them with 
an icon that represents the application. 


mix. An attribute that determines how the 
foreground of a graphic primitive is combined with 
the existing color of graphics output. Also known as 
foreground mix. Contrast with background mix. 


mixed character string. A string containing a 
mixture of one-byte and Kanji or Hangeul (two-byte) 
characters. 


mnemonic. (1) A method of selecting an item on a 
pull-down by means of typing the highlighted letter in 
the menu item. (2) (D of C) In SAA Advanced 
Common User Access architecture, usually a single 
character, within the text of a choice, identified by an 
underscore beneath the character. If all characters 
in a choice already serve as mnemonics for other 
choices, another character, placed in parentheses 
immediately following the choice, can be used. 
When a user types the mnemonic for a choice, the 
choice is either selected or the cursor is moved to 
that choice. 


modal dialog box. In SAA Advanced Common 
User Access architecture, a type of movable window, 
fixed in size, that requires a user to enter information 
before continuing to work in the application window 
from which it was displayed. Contrast with modeless 
dialog box. Also known as a serial dialog box. 
Contrast with parallel dialog box. 


Note: In CUA architecture, this is a programmer 
term. The end user term is pop-up window. 


model space. See graphics model space. 


modeless dialog box. In SAA Advanced Common 
User Access architecture, a type of movable window, 
fixed in size, that allows users to continue their 
dialog with the application without entering 
information in the dialog box. Also known as a 
parallel dialog box. Contrast with modal dialog box. 


Note: In CUA architecture, this is a programmer 
term. The end user term is pop-up window. 


module definition file. A file that describes the 
code segments within a load module. For example, 
it indicates whether a code segment is loadable 
before module execution begins (preload), or 
loadable only when referred to at run time 
(load-on-call). 


mouse. In SAA usage, a device that a user moves 
on a flat surface to position a pointer on the screen. 
It allows a user to select a choice o function to be 
performed or to perform operations on the screen, 
such as dragging or drawing lines from one position 
to another. 


MOUSES. Character-device name reserved for a 
mouse. 


multiple-choice selection. In SAA Basic Common 
User Access architecture, a type of field from which 


a user can select one or more choices or select 
none. See also check box. Contrast with 
extended-choice selection. 


multiple-line entry field. In SAA Advanced 
Common User Access architecture, a control into 
which a user types more than one line of information. 
See also single-line entry field. 


multitasking. The concurrent processing of 
applications or parts of applications. A running 
application and its data are protected from other 
concurrently running applications. 


mutex semaphore. (Mutual exclusion semaphore). 
A semaphore that enables threads to serialize their 
access to resources. Only the thread that currently 
owns the mutex semaphore can gain access to the 
resource, thus preventing one thread from 
interrupting operations being performed by another. 


muxwait semaphore. (Multiple wait semaphore). A 
semaphore that enables a thread to wait either for 
multiple event semaphores to be posted or for 
multiple mutex semaphores to be released. 
Alternatively, a muxwait semaphore can be set to 
enable a thread to wait for any ONE of the event or 
mutex semaphores in the muxwait semaphore’s list 
to be posted or released. 


N 


named pipe. A named buffer that provides 
client-to-server, server-to-client, or full duplex 
communication between unrelated processes. 
Contrast with unnamed pipe. 


national language support (NLS). The 
modification or conversion of a United States English 
product to conform to the requirements of another | 
language or country. This can include the enabling 
or retrofitting of a product and the translation of 
nomenclature, MRI, or documentation of a product. 


nested list. A list that is contained within another 
list. 


NLS. national language support. 
non-8.3 file-name format. A file-naming convention 


in which file names can consist of up to 255 
characters. See also 8.3 file-name format. 
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noncritical extended attribute. An extended 
attribute that is not necessary for the function of an 
application. 


nondestructive read. Reading that does not erase 
the data in the source location. (T) 


noninteractive program. A running program that 
cannot receive input from the keyboard or other input 
device. Compare with active program, and contrast 
with interactive program. 


nonretained graphics. Graphic primitives that are 
not remembered by the Presentation Manager 
interface when they have been drawn. Contrast with 
retained graphics. 


null character (NUL). (1) Character-device name 
reserved for a nonexistent (dummy) device. (2) (D of 
C) A control character that is used to accomplish 
media-fill or time-fill and that may be inserted into or 
removed from a sequence of characters without 
affecting the meaning of the sequence; however, the 
control of equipment or the format may be affected 
by this character. (I) (A) 


null-terminated string. A string of (n+1) characters 
where the (n+1)th character is the ‘null’ character 


(0x00) Also known as ‘zero-terminated’ string and 
"ASCIIZ’ string. 


O 


object. A set of data and actions that can be 
performed on that data. 


Object interface Definition Language (OIDL). 
Specification language for SOM class definitions. 


object window. A window that does not have a 
parent but which might have child windows. An 
object window cannot be presented on a device. 


OIDL. Object Interface Definition Language. 


open. To start working with a file, directory, or other 
object. 


ordered list. Vertical arrangements of items, with 
each item in the list preceded by a number or letter. 


outline font. A set of symbols, each of which is 
created as a series of lines and curves. 
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Synonymous with vector font. Contrast with image 
font. 


output area. An area of storage reserved for 
output. (A) 


owner window. A window into which specific 
events that occur in another (owned) window are 
reported. 


ownership. The determination of how windows 
communicate using messages. 


owning process. The process that owns the 
resources that might be shared with other processes. 


p 


page. (1) A 4KB segment of contiguous physical 
memory. (2) (D of C) A defined unit of space on a 
storage medium. 


page viewport. A boundary in device coordinates 
that defines the area of the output device in which 
graphics are to be displayed. The presentation-page 
contents are transformed automatically to the page 
viewport in device space. 


paint. (1) The action of drawing or redrawing the 
contents of a window. (2) In computer graphics, to 
shade an area of a display image; for example, with 
crosshatching or color. 


panel. In SAA Basic Common User Access 
architecture, a particular arrangement of information 
that is presented in a window or pop-up. If some of 
the information is not visible, a user can scroll 
through the information. 


panel area. An area within a panel that contains 
related information. The three major Common User 
Access-defined panel areas are the action bar, the - 
function key area, and the panel body. 


panel area separator. In SAA Basic Common User 
Access architecture, a solid, dashed, or blank line 
that provides a visual distinction between two 
adjacent areas of a panel. 


panel body. The portion of a panel not occupied by 
the action bar, function key area, title or scroll bars. 
The panel body can contain protected information, 
selection fields, and entry fields. The layout and 
content of the panel body determine the panel type. 


panel body area. See client area. 


panel definition. A description of the contents and 
characteristics of a panel. A panel definition is the 
application developer's mechanism for predefining 
the format to be presented to users in a window. 


panel ID. In SAA Basic Common User Access 
architecture, a panel identifier, located in the 
upper-left corner of a panel. A user can choose 
whether to display the panel ID. 


panel title. In SAA Basic Common User Access 
architecture, a particular arrangement of information 
that is presented in a window or pop-up. If some of 
the information is not visible, a user can scroll 
through the information. 


paper size. The size of paper, defined in either 
standard U.S. or European names (for example, A, 
B, A4), and measured in inches or millimeters 
respectively. 


parallel dialog box. See modeless dialog box. 


parameter list. A list of values that provides a 
means of associating addressability of data defined 
in a called program with data in the calling program. 
It contains parameter names and the order in which 
they are to be associated in the calling and called 
program. 


parent process. In the OS/2 operating system, a 
process that creates other processes. Contrast with 
child process. 


parent window. In the OS/2 operating system, a 
window that creates a child window. The child 
window is drawn within the parent window. If the 
parent window is moved, resized, or destroyed, the 
child window also will be moved, resized, or 
destroyed. However, the child window can be 
moved and resized independently from the parent 
window, within the boundaries of the parent window. 
Contrast with child window. 


partition. (1) A fixed-size division of storage. (2) 
On an IBM personal computer fixed disk, one of four 
possible storage areas of variable size; one may be 
accessed by DOS, and each of the others may be 
assigned to another operating system. 


Paste. A choice in the Edit pull-down that a user 
selects to move the contents of the clipboard into a 
preselected location. See also Copy and Cut. 


path. The route used to locate files; the storage 
location of a file. A fully qualified path lists the drive 
identifier, directory name, subdirectory name (if any), 
and file name with the associated extension. 


PDD. Physical device driver. 


peeking. An action taken by any thread in the 
process that owns the queue to examine queue 


. elements without removing them. 


pel. (1) The smallest area of a display screen 
capable of being addressed and switched between 
visible and invisible states. Synonym for display 
point, pixel, and picture element. (2) (D of C) Picture 
element. 


physical device driver (PDD). A system interface 
that handles hardware interrupts and supports a set 
of input and output functions. 


pick. To select part of a displayed object using the 
pointer. 


pickup. To add an object or set of objects to the 
pickup set. 


pickup and drop. A drag operation that does not 
require the direct manipulation button to be pressed 
for the duration of the drag. 


pickup set. The set of objects that have been 
picked up as part of a pickup and drop operation. 


picture chain. See segment chain. 


picture element. (1) Synonym for pe/. (2) (D of C) 
In computer graphics, the smallest element of a 
display surface that can be independently assigned 
color and intensity. (T) . (3) The area of the finest 
detail that can be reproduced effectively on the 
recording medium. 


PID. Process identification. 


pipe. (1) Anamed or unnamed buffer used to pass 
data between processes. A process reads from or 
writes to a pipe as if the pipe were a standard-input 
or standard-output file. See also named pipe and 
unnamed pipe. (2) (D of C) To direct data so that 
the output from one process becomes the input to 
another process. The standard output of one 
command can be connected to the standard input of 
another with the pipe operator ((). 
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pixel. (1) Synonym for pe/. (2) (D of C) Picture 
element. 


plotter. An output unit that directly produces a 
hardcopy record of data on a removable medium, in 
the form of a two-dimensional graphic 
representation. (T) 


PM. Presentation Manager. 


pointer. (1) The symbol displayed on the screen 
that is moved by a pointing device, such as a 
mouse. The pointer is used to point at items that 
users can select. Contrast with cursor. (2) A data 
element that indicates the location of another data 
element. (T) 


POINTER$. Character-device name reserved for a 
pointer device (mouse screen support). 


pointing device. In SAA Advanced Common User 
Access architecture, an instrument, such as a 
mouse, trackball, or joystick, used to move a pointer 
on the screen. 


pointings. Pairs of x-y coordinates produced by an 
operator defining positions on a screen with a 
pointing device, such as a mouse. 


polyfillet. A curve based on a sequence of lines. 
The curve is tangential to the end points of the first 
and last lines, and tangential also to the midpoints of 
all other lines. See also fillet. 


polygon. One or more closed figures that can be 
drawn filled, outlined, or filled and outlined. 


polyline. A sequence of adjoining lines. 


polymorphism. A concept whereby the behavior of 
an application object is dependent solely upon the 
class and contents of the messages received by that 
object, and is not affected by any other external 
factor. 


pop. To retrieve an item from a last-in-first-out 
stack of items. Contrast with push. 


pop-up window. (1) A window that appears on top 
of another window in a dialog. Each pop-up window 
must be completed before returning to the underlying 
window. (2) (D of C) In SAA Advanced Common 
User Access architecture, a movable window, fixed 
in size, in which a user provides information required 
by an application so that it can continue to pees a 
user request. 
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presentation drivers. Special purpose |/O routines 
that handle field device-independent |/O requests 
from the PM and its applications. 


Presentation Manager (PM). The interface of the 
OS/2 operating system that presents, in windows a 
graphics-based interface to applications and files 
installed and running under the OS/2 operating 
system. 


presentation page. ‘The coordinate space in which 
a picture is assembled for display. 


presentation space (PS). (1) Contains the 
device-independent definition of a picture. (2) (D of 
C) The display space on a display device. 


primary window. In SAA Common User Access 
architecture, the window in which the main 
interaction between the user and the application 
takes place: In a multiprogramming environment, 
each application starts in its own primary window. 
The primary window remains for the duration of the 
application, although the panel displayed will change 
as the user’s dialog moves forward. See also 
secondary window. 


primitive. In computer graphics, one of several 
simple functions for drawing on the screen, including, 
for example, the rectangle, line, ellipse, polygon, and 
so on. 


primitive attribute. A specifiable characteristic of a 
graphic primitive. See graphics attributes. 


print job. The result of sending a document or 
picture to be printed. 


Print Manager. In the Presentation Manager, the 
part of the spooler that manages the spooling 
process. It also allows users to view print queues 
and to manipulate print jobs. 


privilege level. A protection level imposed by the 
hardware architecture of the IBM personal computer. 
There are four privilege levels (number 0 through 3). 
Only certain types of programs are allowed to 
execute at each privilege level. See also [OPL code 
segment. 


procedure cali. In programming languages, a 
language construct for invoking execution of a 
procedure. 


process. An instance of an executing application 
and the resources it is using. 


program. A sequence of instructions that a 
computer can interpret and execute. 


program details. Information about a program that 
is specified in the Program Manager window and is 
used when the program is started. 


program group. In the Presentation Manager, 
several programs that can be acted upon as a single 
entity. 


program name. The full file specification of a 
program. Contrast with program title. 


program title. The name of a program as it is listed 
in the Program Manager window. Contrast with 
program name. 


prompt. A displayed symbol or message that 
requests input from the user or gives operational 
information; for example, on the display screen of an 
IBM personal computer, the DOS A> prompt. The 
user must respond to the prompt in order to proceed. 


protect mode. A method of program operation that 
limits or prevents access to certain instructions or 
areas of storage. Contrast with real mode. 


protocol. A set of semantic and syntactic rules that 
determines the behavior of functional units in 
achieving communication. (l) 


pseudocode. An artificial language used to 
describe computer program algorithms without using 
the syntax of any particular programming 

language. (A) 


pull-down. (1) An action bar extension that displays 
a list of choices available for a selected action bar 
choice. After users select an action bar choice, the 
pull-down appears with the list of choices. Additional 
pop-up windows may appear from pull-down choices 
to further extend the actions available to users. (2) 
(D of C) In SAA Common User Access architecture, 
pertaining to a choice in an action bar pull-down. . 


push. To add an item to a last-in-first-out stack of 
items. Contrast with pop. 


push button. in SAA Advanced Common User 
Access architecture, a rectangle with text inside. 
Push buttons are used in windows for actions that 
occur immediately when the push button is selected. 


putback. To remove an object or set of objects 
from the lazy drag set. This has the effect of 
undoing the pickup operation for those objects 


putdown. To drop the objects in the lazy drag set 
on the target object. 


Q 


queue. (1) A linked list of elements waiting to be 
processed in FIFO order. For example, a queue 
may be a list of print jobs waiting to be printed. (2) 
(D of C) A line or list of items waiting to be 
processed; for example, work to be performed or 
messages to be displayed. 


queued device context. A logical description of a 
data destination (for example, a printer or plotter) 
where the output is to go through the spooler. See 
also device context. 


R 


radio button. (1) A control window, shaped like a 
round button on the screen, that can be in a checked 
or unchecked state. It is used to select a single item 
from a list. Contrast with check box. (2) In SAA 
Advanced Common User Access architecture, a 
circle with text beside it. Radio buttons are 
combined to show a user a fixed set of choices from 
which only one can be selected. The circle is 
partially filled when a choice is selected. 


RAS. Reliability, availability, and serviceability. 


raster. (1) In computer graphics, a predetermined 
pattern of lines that provides uniform coverage of a 
display space. (T) (2) The coordinate grid that 
divides the display area of a display device. (A) 


read-only file. A file that can be read from but not 
written to. 


real mode. A method of program operation that 


does not limit or prevent access to any instructions 
or areas of storage. The operating system loads the 
entire program into storage and gives the program 
access to all system resources. Contrast with 
protect mode. : 


realize. To cause the system to ensure, wherever 
possible, that the physical color table of a device is 
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set to the closest possible match in the logical color 
table. 


recursive routine. A routine that can call itself, or 
be called by another routine that was called by the 
recursive routine. 


reentrant. The attribute of a program or routine that 
allows the same copy of the program or routine to be 
used concurrently by two or more tasks. 


reference phrase. (1) A word or phrase that is 
emphasized in a device-dependent manner to inform 
the user that additional information for the word or 
phrase is available. (2) (D of C) In hypertext, text 
that is highlighted and preceded by a 
single-character input fieid used to signify the 
existence of a hypertext link. 


reference phrase help. In SAA Common User 
Access architecture, highlighted words or phrases 
within help information that a user selects to get 
additional information. 


refresh. To update a window, with changed 
information, to its current status. 


region. A clipping boundary in device space. 


register. A part of internal storage having a 
specified storage capacity and usually intended for a 
specific purpose. (T) 


remote file system. A file-system driver that gains 
access to a remote system without a block device 
driver. 


resource. The means of providing extra information 
used in the definition of a window. A resource can 
contain definitions of fonts, templates, accelerators, 
and mnemonics; the definitions are held in a 
resource file. 


resource file. A file containing information used in 
the definition of a window. Definitions can be of 
fonts, templates, accelerators, and mnemonics. 


restore. To return a window to its original size or 
position following a sizing or moving action. 


retained graphics. Graphic primitives that are 
remembered by the Presentation Manager interface 
after they have been drawn. Contrast with 
nonretained graphics. 
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return code. (1) A value returned to a program to 
indicate the results of an operation requested by that 
program. (2) A code used to influence the execution 
of succeeding instructions. (A) 


reverse video. (1) A form of highlighting a 
character, field, or cursor by reversing the color of 
the character, field, or cursor with its background; for 
example, changing a red character on a black 
background to a black character on a red 
background. (2) In SAA Basic Common User 
Access architecture, a screen emphasis feature that 
interchanges the foreground and background colors 
of an item. 


REXX Language. Restructured Extended Executor. 
A procedural language that provides batch language 
functions along with structured programming 
constructs such as loops; conditional testing and 
subroutines. 


RGB. (1) Color coding in which the brightness of 
the additive primary colors of light, red, green, and 
blue, are specified as three distinct values of white 
light. (2) Pertaining to a color display that accepts 
signals representing red, green, and blue. 


roman. Relating to a type style with upright 
characters. 


root segment. In a hierarchical database, the 
highest segment in the tree structure. 


round-robin scheduling. A process that allows 
each thread to run for a specified amount of time. 


run time. (1) Any instant at which the execution of 
a particular computer program takes place. (T) (2) 
The amount of time needed for the execution of a 
particular computer program. (T) (8) The time 
during which an instruction in an instruction register 
is decoded and performed. Synonym for execution 


time. 


S 


SAA. Systems Application Architecture. 
SBCS. Single-byte character set. 
scheduler. A computer program designed to 


perform functions such as scheduling, initiation, and 
termination of jobs. 


screen. In SAA Basic Common User Access 
architecture, the physical surface of a display device 
upon which information is shown to a user. 


screen device context. A logical description of a 
data destination that is a particular window on the 
screen. See also device context. 


SCREENS. Character-device name reserved for the 
display screen. 


scroll bar. In SAA Advanced Common User 
Access architecture, a part of a window, associated 
with a scrollable area, that a user interacts with to 
see information that is not currently allows visible. 


scrollable entry field. An entry field larger than the 
visible field. 


scrollable selection field. A selection field that 
contains more choices than are visible. 


scrolling. Moving a display image vertically or 
horizontally in a manner such that new data appears 
at one edge, as existing data disappears at the 
opposite edge. 


secondary window. A window that contains 
information that is dependent on information in a 
primary window and is used to supplement the 
interaction in the primary window. 


sector. On disk or diskette storage, an addressable 
subdivision of a track used to record one block of a 
program or data. 


segment. See graphics segment. 


segment attributes. Attributes that apply to the 
segment as an entity, as opposed to the individual 
primitives within the segment. For example, the 
visibility or detectability of a segment. 


segment chain. All segments in a graphics 
presentation space that are defined with the 
‘chained’ attribute. Synonym for picture chain. 


segment priority. The order in which segments are 
drawn. , 


segment store. An area in a normal graphics 
presentation space where retained graphics 
' segments are stored. 


select. To mark or choose an item. Note that 
select means to mark or type in a choice on the 


screen; enter means to send all selected choices to 
the computer for processing. 


select button. The button on a pointing device, 
such as a mouse, that is pressed to select a menu 
choice. Also known as button 1. 


selection cursor. In SAA Advanced Common User 
Access architecture, a visual indication that a user 
has selected a choice. It is represented by outlining 
the choice with a dotted box. See also text cursor. 


selection field. (1) In SAA Advanced Common 
User Access architecture, a set of related choices. 
See also entry field. (2) In SAA Basic Common User 
Access architecture, an area of a panel that cannot 
be scrolled and contains a fixed number of choices. 


semantics. The relationships between symbols and 
their meanings. 


semaphore. An object used by applications for 
signalling purposes and for controlling access to 
serially reusable resources. 


separator. In SAA Advanced Common User 
Access architecture, a line or color boundary that 
provides a visual distinction between two adjacent 
areas. 


serial dialog box. See modal dialog box. 
serialization. The consecutive ordering of items. 


serialize. To ensure that one or more events occur 
in a specified sequence. 


serially reusable resource (SRR). A logical 
resource or object that can be accessed by only one 
task at a time. 


session. (1) A routing mechanism for user 
interaction via the console; a complete environment 
that determines how an application runs and how 
users interact with the application. OS/2 can 
manage more than one session at a time, and more 
than one process can run in a session. Each 
session has its own set of environment variables that 
determine where OS/2 looks for dynamic-link 
libraries and other important files. (2) (D of C) In the 
OS/2 operating system, one instance of a started 
program or command prompt. Each session is 
separate from all other sessions that might be 
running on the computer. The operating system is 
responsible for coordinating the resources that each 
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session uses, such.as computer memory, allocation 
of processor time, and windows on the screen. 


Settings Notebook. A control window that is used 
to display the settings for an object and to enable the 
user to change them. 


shadow box. The area on the screen that follows 
mouse movements and shows what shape the 
window will take if the mouse button is released. 


shared data. Data that is used by two or more 
programs. 


shared memory. In the OS/2 operating system, a 
segment that can be used by more than one 
program. 


shear. In computer graphics, the forward or 
backward slant of a graphics symbol or string of 
such symbols relative to a line perpendicular to the 
baseline of the symbol. 


shell. (1) A software interface between a user and 
the operating system of a computer. Shell programs 
interpret commands and user interactions on devices 
such as keyboards, pointing devices, and 
touch-sensitive screens, and communicate them to 
the operating system. (2) Software that allows a 
kernel program to run under different 
operating-system environments. 


shutdown. The process of ending operation of a 
system or a subsystem, following a defined 
procedure. 


sibling processes. Child processes that have the 
- Same parent process. 


sibling windows. . Child windows that have the 
same parent window. 


simple list. A list of like values; for example, a list 
of user names. Contrast with mixed list. 


single-byte character set (SBCS). A character set 
in which each character is represented by a one-byte 
code. Contrast with double-byte character set. 


slider box. In SAA Advanced Common User 
Access architecture: a part of the scroll bar that 
shows the position and size of the visible information 
in a window relative to the total amount of 
information available. Also known as thumb mark. 


SOM. System Object Model. 
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source file. A file that contains source statements 
for items such as high-level language programs and 
data description specifications. © 


source statement. A statement written ina 
programming language. 


specific dynamic-link module. A dynamic-link 
module created for the exclusive use of an 
application. 


spin button. {In SAA Advanced Common User 
Access architecture, a type of entry field that shows 
a scrollable ring of choices from which a user can 
select a choice. After the last choice is displayed, 
the first choice is displayed again. A user can also 
type a choice from the scrollable ring into the entry 
field without interacting with the spin button. 


spline. A sequence of one or more Bézier curves. 


spooler. A program that intercepts the data going 
to printer devices and writes it to disk. The data is 
printed or plotted when it is complete and the 
required device is available. The spooler prevents 
output from different sources from being intermixed. 


stack. A list constructed and maintained so that the 
next data element to be retrieved is the most 
recently stored. This method is characterized as 
last-in-first-out (LIFO). 


standard window. A collection of window elements 
that form a panel. The standard window can include 
one or more of the following window elements: sizing 
borders, system menu icon, title bar, 
maximize/minimize/restore icons, action bar and 
pull-downs, scroll bars, and client area. 


static control. The means by which the application 
presents descriptive information (for example, 
headings and descriptors) to the user. The user 
cannot change this information. 


static storage. (1) A read/write storage unit in 
which data is retained in the absence of control 
signals. (A) Static storage may use dynamic 
addressing or sensing circuits. (2) Storage other 
than dynamic storage. (A) 


style. See window style. 


subdirectory. In an IBM personal computer, a file 
referred to in a root directory that contains the 


names of other files stored on the diskette or fixed 
disk. 


swapping. (1) A process that interchanges the 
contents of an area of real storage with the contents 
of an area in auxiliary storage. (lI) (A) (2)iIna 
system with virtual storage, a paging technique that 
writes the active pages of a job to auxiliary storage 
and reads pages of another job from auxiliary 
storage into real storage. (3) The process of 
temporarily removing an active job from main 
storage, saving it on disk, and processing another 
job in the area of main storage formerly occupied by 
the first job. 


switch. (1) In SAA usage, to move the cursor from 
one point of interest to another; for example, to 
move from one screen or window to another or from 
a place within a displayed image to another place on 
the same displayed image. (2) In a computer 
program, a conditional instruction and an indicator to 
be interrogated by that instruction. (3) A device or 
programming technique for making a selection, for 
example, a toggle, a conditional jump. 


switch list. See Task List. 


symbolic identifier. A text string that equates to an 
integer value in an include file, which is used to 
identify a programming object. 


symbols. !n Information Presentation Facility, a 
document element used to produce characters that 
cannot be entered from the keyboard. 


synchronous. Pertaining to two or more processes 
that depend upon the occurrence of specific events 
such as common timing signals. (T) See also 
asynchronous. 


System Menu. In the Presentation Manager, the 
pull-down in the top left corner of a window that 
allows it to be moved and sized with the keyboard. 


System Object Model (SOM). A mechanism for 
language-neutral, object-oriented programming in the 
OS/2 environment. 


system queue. The master queue for all pointer 
device or keyboard events. 


system-defined messages. Messages that control 
the operations of applications and provides input an 
other information for applications to process. 


Systems Application Architecture (SAA). A set of 
IBM software interfaces, conventions, and protocols 
that provide a framework for designing and 
developing applications that are consistent across 
systems. 


T 


table tags. !n Information Presentation Facility, a 
document element that formats text in an 
arrangement of rows and columns. 


tag. (1) One or more characters attached to a set of 
data that contain information about the set, including 
its identification. (I) (A) (2) In Generalized 
Markup Language markup, a name for a type of 
document or document element that is entered in the 
source document to identify it. 


target object. An object to which the user is 
transferring information. 


Task List. In the Presentation Manager, the list of 
programs that are active. The list can be used to 
switch to a program and to stop programs. 


template. An ASCll-text definition of an action bar 
and pull-down menu, held in a resource file, or as a 
data structure in program memory. 


terminate-and-stay-resident (TSR). Pertaining to 
an application that modifies an operating system 
interrupt vector to point to its own location (known as 
hooking an interrupt). 


text. Characters or symbols. 


text cursor. A symbol displayed in an entry field - 
that indicates where typed input will appear. 


text window. Also known as the VIO window. 
text-windowed application. The environment in 
which the operating system performs advanced-video 


input and output operations. 


thread. A unit of execution within a process. It 
uses the resources of the process. 


thumb mark. The portion of the scroll bar that 


describes the range and properties of the data that is 
currently visible in a window. Also known as a slider 
box. 
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thunk. Term used to describe the process of 
address conversion, stack and structure realignment, 
etc., necessary when passing control between 16-bit 
and 32-bit modules. 


tilde. A mark used to denote the character that is to 
be used as a mnemonic when selecting text items 
within a menu. 


time slice. (1) An interval of time on the processing 
unit allocated for use in performing a task. After the 
interval has expired, processing-unit time is allocated 
to another task, so a task cannot monopolize 
processing-unit time beyond a fixed limit. (2) In 
systems with time sharing, a segment of time 
allocated to a terminal job. 


time-critical process. A process that must be 
performed within a specified time after an event has 
occurred. 


timer. A facility provided under the Presentation 
Manager, whereby Presentation Manager will 
dispatch a message of class WM_TIMER to a 
particular window at specified intervals. This 
capability may be used by an application to perform 
a specific processing task at predetermined intervals, 
without the necessity for the application to explicitly 
keep track of the passage of time. 


timer tick. See clock tick. 


title bar. In SAA Advanced Common User Access 
architecture, the area at the top of each window that 
contains the window title and system menu icon. 
When appropriate, it also contains the minimize, 
maximize, and restore icons. Contrast with pane/ 
title. 


TLB. Translation lookaside buffer. 


transaction. An exchange between a workstation 
and another device that accomplishes a particular 
action or result. 


transform. (1) The action of modifying a picture by 
scaling, shearing, reflecting, rotating, or translating. 
(2) The object that performs or defines such a 
modification; also referred to as a transformation. 
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Transiation lookaside buffer (TLB). A 
hardware-based address caching mechanism for | 
paging information. 


Tree. In the Presentation Manager, the window in 
the File Manager that shows the organization of 
drives and directories. 


truncate. (1) To terminate a computational process 
in accordance with some rule (A) (2) To remove 
the beginning or ending elements of a string. (3) To 
drop data that cannot be printed or displayed in the 
line width specified or available. (4) To shorten a 
field or statement to a specified length. 


TSR. Terminate-and-stay-resident. 


unnamed pipe. A circular buffer, created in 
memory, used by related processes to communicate 
with one another. Contrast with named pipe. 


unordered list. In Information Presentation Facility, 
a vertical arrangement of items in a list, with each 
item in the list preceded by a special character or 
bullet. 


update region. A system-provided area of dynamic 
storage containing one or more (not necessarily 
contiguous) rectangular areas of a window that are 
visually invalid or incorrect, and therefore are in need 
of repainting. 


user interface. Hardware, software, or both that 
allows a user to interact with and perform operations 
on a system, program, or device. 


User Shell. A component of OS/2 that uses a 
graphics-based, windowed interface to allow the user 
to manage applications and files installed and 
running under OS/2. 


utility program. (1) A computer program in general 
support of computer processes; for example, a 
diagnostic program, a trace program, a sort 
program. (T) (2) A program designed to perform 
an everyday task such as copying data from one 
storage device to another. (A) 


U 


There are no glossary terms for this starting letter. 


V 


value set control. A visual component that enables 
a user to select one choice from a group of mutually 
exclusive choices. 


vector font. A set of symbols, each of which is 
created as a series of lines and curves. 
Synonymous with outline font. Contrast with image 
font. 


VGA. Video graphics array. 


viewing pipeline. The series of transformations 
applied to a graphic object to map the object to the 
device on which it is to be presented. 


viewing window. A clipping boundary that defines 
the visible part of model space. 


VIO. Video Input/Output. 


virtual memory (VM). Synonymous with virtual 
storage. 


virtual storage. (1) The storage space that may be 
regarded as addressable main storage by the user of 
a computer system in which virtual addresses are 
mapped into real addresses. The size of virtual 
storage is limited by the addressing scheme of the 
computer system and by the amount of auxiliary 
storage available, not by the actual number of main 
storage locations. (I) (A) (2) Addressable space 
that is apparent to the user as the processor storage 
space, from which the instructions and the data are 
mapped into the processor storage locations. (3) 
Synonymous with virtual memory. 


visible region. A window's presentation space, 
clipped to the boundary of the window and the 
boundaries of any overlying window. 


volume. (1) A file-system driver that uses a block 
device driver for input and output operations to a 
local or remote device. (I) (2) A portion of data, 
together with its data carrier, that can be handled 
conveniently as a unit. 


W 


wildcard character. Synonymous with global 
file-name character. 


window. (1) A portion of a display surface in which 
display images pertaining to a particular application 
can be presented. Different applications can be 
displayed simultaneously in different windows. (A) 
(2) An area of the screen with visible boundaries 
within which information is displayed. A window can 
be smaller than or the same size as the screen. 
Windows can appear to overlap on the screen. 


window class. The grouping of windows whose 
processing needs conform to the services provided 
by one window procedure. 


window coordinates. A set of coordinates by 
which a window position or size is defined; measured 
in device units, or pels. 


window handle. Unique identifier of a window, 
generated by Presentation Manager when the 
window is created, and used by applications to direct 
messages to the window. 


window procedure. Code that is activated in 
response to a message. The procedure controls the 
appearance and behavior of its associated windows. 


window rectangle. The means by which the size 
and position of a window is described in relation to 
the desktop window. 


window resource. A read-only data segment 
stored in the .EXE file of an application o the .DLL 
file of a dynamic link library. 


window style. The set of properties that influence 
how events related to a particular window will be 
processed. 


window title. In SAA Advanced Common User 
Access architecture, the area in the title bar that 
contains the name of the application and the OS/2 
operating system file name, if applicable. 


workstation. (1) A display screen together with 
attachments such as a keyboard, a local copy 
device, or a tablet. (2) (D of C) One or more 
programmable or nonprogrammable devices that 
allow a user to do work. 
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world coordinates. A device-independent 
Cartesian coordinate system used by the application 
program for specifying graphical input and 

output. (I) (A) 


world-coordinate space. Coordinate space in 
which graphics are defined before transformations 
are applied. 

WYSIWYG. What-You-See-ls-What-You-Get. A 


capability of a text editor to continually display pages 
exactly as they will be printed. 


X 


There are no glossary terms for this starting letter. 


Y 


There are no glossary terms for this starting letter. 
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Z 


z-order. The order in which sibling windows are 
presented. The topmost sibling window obscures 
any portion of the siblings that it overlaps; the same 
effect occurs down through the order of lower sibling 
windows. 


zooming. The progressive scaling of an entire 
display image in order to give the visual impression 
of movement of all or part of a display group toward 
or away from an observer. (I) (A) 


8.3 file-name format. A file-naming convention in 
which file names are limited to eight characters 
before and three characters after a single dot. 
Usually pronounced “eight-dot-three.” See also 
non-8.3 file-name format. 
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ACCEL A-1 
ACCELTABLE A-1 
ACCELTABLE statement 31-10 
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APIRET A-2 
Applications 
Windowed PM_ 32-1 
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ARCPARAMS A-2 
AREABUNDLE A-3 
ASSOCTABLE statement 31-9, 31-12 
ATOM A-4 


BDS _* values 11-6 
bit maps 

data D-1 

example D-2 

file format D-2 

information tables D-1 

standard formats D-1 
BIT16 A-20 
BIT32 A-20 
BIT8 A-20 
BITMAPARRAYFILEHEADER A-4 
BITMAPARRAYFILEHEADER2 A-5 
BITMAPFILEHEADER' A-6 
BITMAPFILEHEADER2 A-7 
BITMAPINFO A-8 
BITMAPINFO2 A-9 
BITMAPINFOHEADER' A-14 
BITMAPINFOHEADER2 A-15 
BKM_CALCPAGERECT 23-7 
BKM_DELETEPAGE 23-8 
BKM_INSERTPAGE .23-9 
BKM_INVALIDATETABS 23-11 
BKM_QUERYPAGECOUNT 23-11 
BKM_QUERYPAGEDATA 23-13 
BKM_QUERYPAGEID 23-13 
BKM_QUERYPAGEINFO 23-15 
BKM _QUERYPAGESTYLE 23-16 
BKM_QUERYPAGEWINDOWHWND_ 23-17 
BKM_QUERYSTATUSLINETEXT 23-18 
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BKM_QUERYTABBITMAP 23-19 
BKM_QUERYTABTEXT 23-19, 23-20 
BKM_SETDIMENSIONS 23-20, 23-21 
BKM_SETNOTEBOOKCOLORS 23-21, 23-22 
BKM_SETPAGEDATA 23-23 
BKM_SETPAGEINFO 23-24 
BKM_SETPAGEWINDOWHWND 23-24, 23-25 
BKM_SETSTATUSLINETEXT 23-26 
BKM_SETTABBITMAP 23-26 
BKM_SETTABTEXT 23-28 
BKM_TURNTOPAGE 23-28, 23-29 
BKN_* values 23-3 

BKS _* values 23-1 

BM_CLICK 11-8 
BM_QUERYCHECK 11-8 
BM_QUERYCHECKINDEX 11-9 
BM_QUERYHILITE 11-10 
BM_SETCHECK 11-11 
BM_SETDEFAULT 11-12 
BM_SETHILITE 11-13 

BN_* values 11-6 
BOOKPAGEINFO A-21 

BOOKTEXT A-23 

BOOL A-21 

BS * values 11-1 

BTNCDATA A-24 

button control data 11-3 

button control styles 11-1 

bution control window processing 11-1 
BYTE A-24 
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CA_* values A-36 
column headings A-37 
drawing and painting A-37 
icons or bit maps A-36 
ordered target emphasis A-36 
title attributes A-37 
title position A-37 
tiles A-37 
CATCHBUF A-25 
CBM_HILITE 17-6 
CBM_ISLISTSHOWING 17-7 
CBM_SHOWLIST 17-7 
CBN_* values 17-3 
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CBS _* values 17-1 
CCS _* values 

selection types 22-3 

styles 22-2 
CDATE A-25 
CDP parameter A-52 
CF_* values 27-5 
CFA_* values A-73 

data types A-73 
CHAR A-26 
CHARBUNDLE A-26 
check box 11-1 
CLASSINFO A-27 
clipboard 26-27 

messages 26-27 
Clipboard messages 26-27, 27-1 
clipping F-1 
CM_ALLOCDETAILFIELDINFO 22-31 
CM_ALLOCRECORD 22-32 
CM_ARRANGE 22-34 
CM_CLOSEEDIT 22-35 
CM_COLLAPSETREE 22-36 
CM_ERASERECORD 22-37 
CM_EXPANDTREE 22-38 
CM_FILTER 22-39 
CM_FREEDETAILFIELDINFO 22-40 
CM_FREERECORD 22-42 
CM_HORZSCROLLSPLITWINDOW 22-43 
CM_INSERTDETAILFIELDINFO 22-44 
CM_INSERTRECORD 22-45 
CM_INSERTRECORDARRAY 22-47 
CM_INVALIDATEDETAILFIELDINFO 22-49 
CM_INVALIDATERECORD 22-50 
CM_MOVETREE 22-52 
CM_OPENEDIT 22-53 
CM_PAINTBACKGROUND 22-55 
CM_QUERYCNRINFO 22-56 
CM_QUERYDETAILFIELDINFO 22-56 
CM_QUERYDRAGIMAGE 22-57 
CM_QUERYRECORD 22-59 
CM_QUERYRECORDEMPHASIS 22-60 
CM_QUERYRECORDFROMRECT 22-61 
CM_QUERYRECORDINFO 22-63 
CM_QUERYRECORDRECT 22-64 
CM_QUERYVIEWPORTRECT 22-65 
CM_REMOVEDETAILFIELDINFO 22-66 
CM_REMOVERECORD 22-68 
CM_SCROLLWINDOW 22-70 
CM_SEARCHSTRING 22-70 
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CM_SETCNRINFO 22-71 
CM_SETRECORDEMPHASIS 22-74 
CM_SETTEXTVISIBILITY 22-77 
CM_SORTRECORD 22-76 


CMDSRC_* values 9-4, 10-37, 10-49, 10-91, 13-28 


CN_* values 22-5 

described 22-10 
CN_BEGINEDIT 22-10 
CN_COLLAPSETREE 22-10 
CN_CONTEXTMENU 22-12 
CN_DRAGAFTER 22-12 
CN_DRAGLEAVE 22-15 
CN_DRAGOVER 22-16 
CN_DROP 22-18 
CN_DROPHELP 22-19 
CN_DROPNOTIFY 22-19 
CN_EMPHASIS 22-20 
CN_ENDEDIT 22-21 
CN_ENTER 22-22 
CN_EXPANDTREE 22-23 
CN_HELP 22-23 
CN_INITDRAG 22-24 
CN_KILLFOCUS 22-25 
CN_PICKUP 22-26 
CN_QUERYDELTA 22-27 
CN_REALLOCPSZ 22-28 
CN_SCROLL 22-29 
CN_SETFOCUS 22-29 
CNRDRAGINFO  A-27, A-28 
CNRDRAGINIT A-32 
CNRDRAWITEMINFO A-28 
CNREDITDATA A-29 
CNRINFO A-32, A-33 
CNRLAZYDRAGINFO A-39 
Code pages 32-1 

ASCIl 32-12 

EBCDIC 32-21 

Font support 32-4 

OS/2 options for PM 32-3 

OS/2 support for multiple 32-4 
COL parameter A-52 
COLOR A-40 
color table F-1 
combination-box control data 17-1 
combination-box control window processing 
container contro! window processing 

data structures 22-4 

icon size, how determined A-35 

‘mini-icon size, how determined A-35 

notification codes 22-10 


container contro! window processing (continued) 
notification messages 22-5 
purpose 22-1 
styles and selection types 22-2 
window messages 22-31 
window words 22-2 
container views A-34 
contents and format of dialog template 31-24 
control classes 9-2 
control data 31-28 
control statements 
predefined 31-30 
control window processing 9-2 
Control-Data A-44 
CONVCONTEXT A-40 
coordinates 
dialog 31-24 
coordinates for dialogs 31-24 
COP parameter A-51 
CREATESTRUCT A-41 
CS_* values 
window class styles 10-2 
CSBITMAPDATA A-42 
CSM_QUERYINCREMENT 25-5 
CSM_QUERYRADIUS 25-5 
CSM_QUERYRANGE 25-6 
CSM_QUERYVALUE 25-6 
CSM_SETBITMAPDATA 25-7 
CSM_SETINCREMENT 25-7 
CSM_SETRANGE 25-8 
CSM_SETVALUE 25-9 


CTIME A-44 

CURSORINFO A-43 

CV_* values 
CNRINFO A-34 


SEARCHSTRING A-185 
view styles A-35 
CVR_* values 10-30 


D 


data 
bit map D-1 
data area in a dialog template 31-27 
DC_* values A-61 , 
DDE_* values 29-1, 29-2, 29-3, A-47 
DDEINIT A-45 
DDESTRUCT A-46 
default colors 11-3, 12-3, 13-4, 14-1, 15-3, 17-2, 
18-1, 20-2, 21-1, 25-2 


default dialog processing 10-103 
default message processing 10-1 
default window processing 9-2 
DEFAULTICON keyword 31-3 
DELETENOTIFY A-46 
DESKTOP A-48 
DEVOPENSTRUC A-49 
Dialog and Window Template statement 31-9 
dialog processing 10-103 

default 10-103 

language support 10-120 
dialog template 

data-area information 31-27 

format and contents 31-24 

header information 31-26 

item information 31-26 
direct manipulation messages 28-1 
directives 31-6 
DLGC_* values 10-105 
DLGTEMPLATE A-53 
DLGTEMPLATE statement 31-13 
DLGTITEM A-54 
DM_DISCARDOBJECT 28-1 
DM_DRAGERROR 28-1 
DM_DRAGFILECOMPLETE 28-2 
DM_DRAGLEAVE 28-4 
DM_DRAGOVER 28-4 
DM_DRAGOVERNOTIFY 28-7 
DM_DROP 28-8 
DM_DROPHELP 28-9 
DM_DROPNOTIFY 28-10 
DM_EMPHASIZETARGET 28-11 
DM_ENDCONVERSATION 28-11 
DM_FILERENDERED 28-12 
DM_PRINTOBJECT 28-13 
DM_RENDER 28-14 
DM_RENDERCOMPLETE 28-15 
DM_RENDERFILE 28-17 
DM_RENDERPREPARE 28-18 
DMFL_* values. A-63 
DO_* values 

DRAGINFO A-58 

DRAGITEM A-61 
drag messages 28-1 
DRAGIMAGE A-56 
DRAGINFO A-57 
DRAGITEM A-58 
DRAGTRANSFER_ A-61 
DRF_* values A-60 
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DRG_* values A-56 FIELDINFOINSERT A-75 


DRIVDATA A-63 file dialog 10-106 
DRM_* values A-60 file format 
DRT_* vaiues A-59 file formats 
DT_* values 20-1 bitmaps D-2 
dynamic data exchange messages 29-1 icon file D-2 
pointer D-2 

FILEDLG A-77 
E FIT parameter A-51 
EM_ CLEAR 12-6 FIXED A-81 
EM_COPY 12-6 FNTF_* values A-84, A-85 
EM_CUT 12-7 FNTM_FACENAMECHANGED 10-111 
EM_PASTE 12-8 FNTM_FILTERLIST 10-112 
‘EM_QUERYCHANGED 12-8 © FNTM_POINTSIZECHANGED 10-113 
EM _QUERYFIRSTCHAR 12-9 FNTM_STYLECHANGED 10-114 
EM_QUERYREADONLY 12-10 FNTM_UPDATEPREVIEW 10-115 
EM_QUERYSEL 12-11 FNTS_* values A-83 
EM_SETFIRSTCHAR 12-12 font dialog 10-109 
EM_SETINSERTMODE 12-13 FONTDLG A-82 
EM_SETREADONLY 12-13 FONTMETRICS A-88 
EM_SETSEL 12-14 fonts supplied with the OS/2 operating system E-1 
EM_SETTEXTLIMIT 12-15 format and contents of dialog template 31-24 
EN _* values 12-4, 16-3 frame contro! data 13-3 
entry field control data 12-3 frame control window processing 13-1 
entry field control window processing 12-1 FRAMECDATA A-98 
ENTRYFDATA A-64 FS_* values 13-3 
ERRINFO A-65 
ERRORID A-65 
errors B-1, C-1 G 
ES *dbcsvals 12-2 general window styles 10-1 
ES _* values 12-1 GRADIENTL A-100 


ESCMODE A-66 
ESCSETMODE A-67 


H. 


HAB A-100 
F HACCEL A-100 
FACENAMEDESC A-68 HAPP. A-101 
FATTR_SEL _* values A-70 HATOMTBL A-101 
FATTR_TYPE_* values A-71 HBITMAP A-101 
FATTRS A-69 HCAPS _* values A-103 
FCF_* values 13-1 HCINFO A-102 
FDM_ERROR_ 10-106 HDC A-102 
FDM_FILTER 10-107 HDDF A-103 
FDM_VALIDATE 10-108 header 31-26 
FDS _* values A-78 help manager messages 30-1 
FFDESCS A-71 HELPINIT A-104 
Fl_* values 13-23 HELPSUBTABLE A-106 
FID_* values 13-1, 21-1 HELPTABLE: A-108 


FIELDINFO A-72 HENUM A-108 
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HEV A-108 

HIN! A-108 

HLIB A-109 
HM_ACTIONBAR_COMMAND 30-1 
HM CONTROL 30-1 
HM_CREATE_HELP_TABLE 30-2 
HM_DISMISS_WINDOW 30-3 
HM_DISPLAY_HELP 30-4 
HM_ERROR 30-5 
HM_EXT_HELP 30-7 
HM_EXT_HELP_UNDEFINED 30-8 
HM_GENERAL_HELP 30-8 


HM_GENERAL_HELP_UNDEFINED 30-9 


HM_HELP_CONTENTS 30-10 
HM_HELP_INDEX 30-10 


HM_HELPSUBITEM_NOT_FOUND 30-11 


HM_INFORM 30-12 


HM_INVALIDATE_DDF_DATA 30-12 


HM_KEYS_HELP 30-14 
HM_LOAD_HELP_TABLE 30-15 
HM_NOTIFY 30-15 
HM_QUERY 30-17 
HM_QUERY_DDF_DATA 30-19 
HM_QUERY_KEYS HELP 30-20 


HM_REPLACE_HELP_FOR_HELP 30-20 


HM_REPLACE_USING_HELP 30-21 
HM_SET_ACTIVE_WINDOW 30-22 


HM_SET_COVERPAGE_SIZE 30-23 
HM_SET_HELP_LIBRARY_NAME 30-24 
HM_SET_HELP_WINDOW_TITLE 30-25 
HM_SET_OBJCOM_WINDOW 30-25 


HM_SET SHOW_PANEL_ID 30-26 
HM_SET_USERDATA 30-27 
HM TUTORIAL 30-27 


HM_UPDATE_OBJCOM_WINDOW_CHAIN 30-28 


HMERR _* error constants 30-5 
HMF A-109 
HMODULE A-109 
HMQ_ A-110 
HMTX A-110 
HMUX A-110 
HOBJECT A-110 
HPOINTER A-111 
HPROGRAM A-111 
HPS A-111 
HRGN A-111 
HSAVEWP A-112 
HSEM A-112 
HSPL A-112 


HSTR A-112 
HSWITCH A-113 
HT_* values 10-50 
HWND A-113 


icon file format D-2 
icon size, how determined A-35 
ICONINFO A-113 
IMAGEBUNDLE A-114 
information tables 

bitmap D-1 
initialization file G-1 
interchange file format F-1 


IPT A-115 


items in a dialog template 31-26 


J 


JRN_* values 10-54 


K 


KC_* values 10-32 
kerning A-98 

enable A-71 

number of pairs A-98 
KERNINGPAIRS A-115 
KERNINGPAIRS data structure A-115 
keyboard control codes 10-32 
keyboard resources 31-10 
keyboard statements 

keyboard 31-10 


L 


language support dialog processing 10-120 
language support window processing 10-116 
LBOXINFO A-115 

LHANDLE A-117 

LINEBUNDLE A-117 

list box control data 14-1 

list box control styles 14-1 

list box control window processing 14-1 
LIT_* values 14-8 

LM_DELETEALL 14-7 

LM_DELETEITEM 14-7 
LM_INSERTITEM 14-8 
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LM_INSERTMULTITEMS 14-9 
LM_QUERYITEMCOUNT 14-10 
LM_QUERYITEMHANDLE 14-11 
LM_QUERYITEMTEXT 14-12 
LM_QUERYITEMTEXTLENGTH 14-13 
LM_QUERYSELECTION 14-13 
LM_QUERYTOPINDEX 14-14 
LM_SEARCHSTRING 14-15 
LM_SELECTITEM 14-16 
LM_SETITEMHANDLE 14-18 
LM_SETITEMHEIGHT 14-19 
LM_SETITEMTEXT 14-19 
LM_SETITEMWIDTH 14-20 
LM_SETTOPINDEX 14-21 
LN_* values 14-3 

LONG A-118 

LS_* values 14-1 

LSS_* values 14-15 


MAP parameter A-52 
MARKERBUNDLE A-119 
MATRIXLF A-120 
MB2D A-121 
MB2INFO A-121 
menu control styles 15-1 
menu control window processing 15-1 
menu item attributes 15-3 
menu item styles 15-2 
MENU statement 31-9, 31-16 
MENUITEM A-123 
menus 
pull-down 31-19 
templates 31-20 
message processing 
introduction 9-1 
notation conventions 9-4 
types 9-1 
message types 9-1 
Metafile data format F-3 
metafile restrictions F-1 
metafiles 
general rules F-1 
MIA_* values 15-3 
mini-icon size, how determined A-35 
MINIRECORDCORE A-124 
MIS_* values 15-2, 31-21 
MIT_* values 15-12, 15-15, 15-23 
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MLE_SEARCHDATA A-125 
MLECTLDATA A-127 
MLEMARGSTRUCT A-126 
MLEOVERFLOW A-136 
MLM_CHARFROMLINE 16-9 
MLM_CLEAR 16-9 

MLM_COPY 16-10 

MLM_CUT 16-11 

MLM_DELETE 16-12 
MLM_DISABLEREFRESH 16-12 
MLM_ENABLEREFRESH 16-13 
MLM_EXPORT 16-14 
MLM_FORMAT 16-15 
MLM_IMPORT. 16-16 
MLM_INSERT 16-17 
MLM_LINEFROMCHAR 16-18 
MLM_PASTE 16-18 
MLM_QUERYBACKCOLOR 16-19 
MLM_QUERYCHANGED 16-19 
MLM_QUERYFIRSTCHAR 16-20 
MLM_QUERYFONT 16-21 
MLM_QUERYFORMATLINELENGTH 16-21 
MLM_QUERYFORMATRECT 16-22 
MLM_QUERYFORMATTEXTLENGTH 16-23 
MLM_QUERYIMPORTEXPORT 16-24 
MLM_QUERYLINECOUNT 16-25 
MLM_QUERYLINELENGTH 16-25 
MLM_QUERYREADONLY 16-26 
MLM_QUERYSEL 16-27 
MLM_QUERYSELTEXT 16-29 
MLM_QUERYTABSTOP 16-29 
MLM_QUERYTEXTCOLOR 16-30 
MLM_QUERYTEXTLENGTH 16-31 
MLM_QUERYTEXTLIMIT 16-31 
MLM_QUERYUNDO 16-32 
MLM_QUERYWRAP 16-33 
MLM_RESETUNDO 16-33 
MLM_SEARCH 16-35 
MLM_SETBACKCOLOR 16-37 
MLM_SETCHANGED 16-37 
MLM_SETFIRSTCHAR 16-38 
MLM_SETFONT 16-39 
MLM_SETFORMATRECT 16-40 
MLM_SETIMPORTEXPORT 16-43 
MLM_SETREADONLY 16-43 
MLM_SETSEL 16-45 
MLM_SETTABSTOP 16-46 
MLM_SETTEXTCOLOR 16-46 
MLM_SETTEXTLIMIT 16-47 


MLM_SETWRAP_ 16-48 
MLM_UNDO_ 16-49 
MLS_* values 16-2 
MM_DELETEITEM 15-10 
MM_ENDMENUMODE 15-10 
MM_INSERTITEM 15-11 
MM_ISITEMVALID 15-12 
MM_ITEMIDFROMPOSITION 15-13 
MM_ITEMPOSITIONFROMID 15-14 
MM_QUERYDEFAULTITEMID 15-15 
MM_QUERYITEM 15-15 
MM_QUERYITEMATTR 15-16 
MM_QUERYITEMCOUNT 15-18 
MM_QUERYITEMRECT 15-18 
MM_QUERYITEMTEXT 15-19 
MM_QUERYITEMTEXTLENGTH 15-20 
MM_QUERYSELITEMID 15-21 
MM_REMOVEITEM 15-22 
MM_SELECTITEM 15-23 
MM_SETDEFAULTITEMID 15-24 
MM_SETITEM 15-25 
MM_SETITEMATTR 15-26 
MM_SETITEMHANDLE 15-27 
MM_SETITEMTEXT 15-28 
MM_STARTMENUMODE 15-28 
MPARAM A-129 
MQINFO A-129 
MRESULT A-130 
MS_* values 10-8, 15-1 
multi-line entry field control data 16-2 
multi-line entry field control window processing 16-1 
multiple-line statements 31-9 

ACCELTABLE 31-10 

ASSOCTABLE 31-12 

DLGTEMPLATE 31-13 

MENU 31-16 

STRINGTABLE 31-22 

WINDOWTEMPLATE 31-13 
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notation conventions 
messages 9-4 

notebook control window processing 
notification codes 23-3 
notification messages 23-3 
purpose 23-1 
styles 23-1 
window messages 23-7 


NOTIFYDELTA A-130 
NOTIFYRECORDEMPHASIS  A-131 
NOTIFYRECORDENTER A-132 
NOTIFYSCROLL A-133 
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OBJCLASS A-134 
owner-notification messages 9-4 
OWNERBACKGROUND:  A-135 
OWNERITEM 10-110, A-136 
owneritem parameter 22-7 
WM_DRAWITEM for container control 22-7 
WM_DRAWITEM for font dialog 10-110 
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PAGEINFO A-138 
PAGESELECTNOTIFY A-140 
PANOSE A-140 
PARAM A-144 
parent/child/owner relationship 31-29 
PC VKEY H-1 
PCH A-147 
PCSZ A-147 
PDEVOPENDATA A-147 
PFN A-148 
PFNWP A-148 
PID A-148 
PIX A-148 
PL_ALTERED 10-5 
PM_* names G-1 
PM_Q_* values A-50 
pointer file format D-2 
POINTERINFO A-169 
POINTL A-170 
POINTS A-171 
PQMOPENDATA  A-171 
PRD_* values. A-150 
PRDINFO3S A-149 
PRDRIVINFO A-151 
predefined control statements 31-30 
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